diff --git a/.gitignore b/.gitignore
index 0ff3a2c..406f4a4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,7 +11,6 @@ frontend/public/sw.js
 frontend/next-env.d.ts
 package-lock.json
 !backend/package-lock.json
-AGENTS.md
 .codex/
 
 !frontend/package-lock.json
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6f9622b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,447 @@
+# AGENTS.md
+
+This file provides guidance to CODEX when working with code in this repository.
+
+**MAIN RULE:** DON'T MADE UP ANYTHING!!! IF YOU NOT SURE - DOUBLECHECK IT VIA PROJECT DOCUMENTATION, TOOL DOCUMENTATION, APPROPRIATE MCP, WEB SEARCH OR JUST ASK FOR ME TO CLARIFY. 
+
+## Project Overview
+
+Tour Builder Platform - a web application for building and managing interactive virtual tours. Built with:
+- **Frontend**: Next.js 15 with React 19, TypeScript, Redux Toolkit, Tailwind CSS
+- **Backend**: Node.js/Express with Sequelize ORM
+- **Database**: PostgreSQL
+
+## System Requirements
+
+### Required Software
+- **Node.js** 24.x for backend runtime and TypeScript migration work
+- **PostgreSQL** 14+
+
+### FFmpeg
+
+FFmpeg is bundled with the backend via `ffmpeg-static` and `ffprobe-static` npm packages. No manual installation is required.
+
+**How it works:**
+- Pre-compiled binaries are downloaded during `npm install`
+- `fluent-ffmpeg` is configured to use bundled binaries in `backend/src/services/videoProcessing.js`
+- Works across all platforms (Linux, macOS, Windows) and Docker environments
+
+**Supported use case:**
+- Reversed video generation for back navigation transitions
+
+## Important Rules
+
+- **Never change global app configs casually** - Do not modify `.env` or database configuration without verifying the target environment. These configs are shared across environments and incorrect changes can break production.
+- **Centralize environment variables** - Do not read new app/runtime environment variables directly from services, routes, components, hooks, or feature modules. Backend app env vars must be added to `backend/src/utils/env-validation.ts`, typed in `backend/src/types/env.ts` / `backend/src/types/config.ts`, exposed through `backend/src/config.ts`, and consumed via `config`. Frontend public env vars must be centralized in `frontend/src/config.ts`. Direct `process.env` access is acceptable only in bootstrap/config entrypoints (`load-env`, logger bootstrap, DB/Umzug config, Next config), scripts, migrations, seeders, and tests.
+- **Backend async handlers** must be wrapped with `wrapAsync` helper for error propagation.
+- **Use Passport JWT** for protected routes: `passport.authenticate('jwt', { session: false })`. Secure routes must read the authenticated user through `getCurrentUser(req)` from `backend/src/utils/request-context.ts`; if absent, return `ForbiddenError`.
+- **Access model** - Keep the current permission model: effective permissions are `app_role.permissions + user.custom_permissions`. `Administrator`, `Platform Owner`, and `Account Manager` are platform-wide internal roles. Other internal users currently have all-project scope by default unless a future explicit override system is implemented. `Public` users must not have admin API permissions and can only access public production pages plus explicitly granted private production presentations.
+- **Public role hardening** - Do not grant RBAC permissions or custom permissions to `Public` users. Do not represent private production presentation grants as `READ_PROJECTS`, `READ_TOUR_PAGES`, or other admin permissions; use `production_presentation_access`.
+- **Centralize access decisions** - New authorization logic must go through an `AccessPolicy`-style helper/service rather than ad hoc checks in routes/components. Keep admin API permissions separate from runtime presentation access.
+
+## Mandatory Rules For New Code
+
+These rules are required for new code and for touched code when practical.
+
+### Backend Boundaries
+- **Routes/controllers**: only authenticate, read runtime context, validate request input, call a service, and map the response. Do not put business logic in routes.
+- **Services/domain**: own business logic, transactions, permission decisions, and orchestration.
+- **DB API/repository**: only data access, filters, includes, pagination, and persistence mapping.
+- **Policy**: all role/permission/runtime access decisions belong in policy/helper services, not scattered across routes.
+- **Validation**: all new external `body`, `query`, and `params` inputs must be validated before service calls. `Joi` is already available in backend and should be preferred unless there is a clear reason to use another validator.
+- **ID handling**: route params are canonical. For `PUT/PATCH/DELETE /:id`, use `req.params.id`; reject mismatched body ids.
+- **Query safety**: new list/autocomplete endpoints must define max `limit`, default pagination, allowed sort fields, and allowed sort directions.
+- **Service contracts**: new service/DB API methods should use object/options signatures, e.g. `Service.update({ id, data, currentUser, transaction, runtimeContext })` and `DBApi.findAll(filter, { currentUser, transaction, runtimeContext })`.
+- **Logging**: use the project logger in runtime backend code (`services`, `routes`, `middlewares`, `db/api`, `utils`, app/bootstrap/config). Do not add new `console.*` calls outside migrations, seeders, scripts, or explicit debug-only CLI tooling.
+
+### Backend Typing
+- New backend pure helpers, validators, and policy modules should use TypeScript or JSDoc/checkJs-compatible types.
+- Define shared shapes for `currentUser`, `runtimeContext`, service options, and validation results when touching related code.
+- Do not add global `Express.Request` augmentation for project request fields. Use `backend/src/utils/request-context.ts` helpers for request-scoped `currentUser`, `runtimeContext`, logging, runtime-public flags, and permission overrides.
+- Keep active backend source in strict TypeScript/ESM.
+
+### Frontend State And API
+- **Redux is for client/app state only**: auth/session UI, theme/style, layout/sidebar, constructor UI state, and app preferences.
+- **TanStack Query is for server state**: API reads, entity lists/details, mutations, invalidation, and background refetch.
+- Do not create new entity CRUD Redux slices or new Redux thunks for server reads/mutations.
+- Centralize API access through query hooks or a shared API client. Avoid direct `axios` calls inside feature UI components unless there is a clear existing local pattern.
+- New feature-specific code should live near the feature/domain it belongs to. Do not put feature logic into generic `components`, `hooks`, or `lib` folders when a feature-local module is clearer.
+
+### Frontend TypeScript And React
+- Do not add new `any` without a specific reason. Prefer existing domain types or add a narrow local type.
+- Avoid new `eslint-disable`, `@ts-ignore`, and hook dependency suppressions. If unavoidable, add a short reason.
+- New hooks must follow React hook rules and should be structured so `react-hooks/exhaustive-deps` can be enabled.
+- Do not add new client usage of `jsonwebtoken`; use `jwt-decode` or `/auth/me` for client-side identity.
+
+### Database And Migrations
+- Do not add indexes speculatively. Add indexes after checking query patterns or explaining the expected query.
+- Migrations must be reversible or include an explicit rollback/backup plan.
+- Do not drop columns/tables in the same change that stops using them unless explicitly requested and production data safety is covered.
+- Do not normalize `ui_schema_json` into new tables unless there is a concrete current need; prefer validation/extraction helpers first.
+- Do not rewrite, rename, or reformat already applied backend migration files. Add new migrations only for new schema changes.
+
+## Disabled Features
+
+The following features are implemented but currently disabled with `false &&` conditions:
+
+- **Navigation blocking while preloading** - Navigation buttons can be disabled until neighbor page backgrounds are preloaded. Currently disabled to allow instant navigation response. To re-enable, remove `false &&` in:
+  - `frontend/src/components/RuntimePresentation.tsx` (isForwardNavDisabled, handleElementClick)
+  - `frontend/src/pages/constructor.tsx` (handleElementClick, isNavDisabled calculation)
+
+## Documentation Workflow
+
+- **Before each task**: Research relevant documentation in `documentation/` to understand existing implementations, patterns, and conventions.
+- **After each task**: Update affected documentation to reflect changes (API changes, new fields, modified workflows).
+- **After implementing new features/modules**: Create new documentation file in `documentation/` following the existing format, and add reference to the Feature Documentation table in this file.
+
+## Quick Start
+```bash
+# Terminal 1 - Backend (port 3000)
+cd backend && npm run start-dev
+
+# Terminal 2 - Frontend (port 3001)
+cd frontend && npm run dev
+```
+
+## Common Commands
+
+### Backend (run from `backend/` directory, runs on port 3000 in the default dev_stage flow)
+```bash
+npm install              # Install dependencies
+npm run start-dev        # Start server (loads .env, migrates, seeds, watches)
+npm run lint             # ESLint check
+npm run typecheck        # Strict TypeScript check for migrated backend scope
+npm run test             # Unit tests (Node test runner)
+npm run test:integration # Integration tests; DB tests skip when Postgres is unavailable
+npm run test:e2e         # E2E HTTP tests with a local listener
+npm run test:all         # Unit, integration, and e2e suites
+npm run build            # Compile migrated TypeScript files
+npm run db:migrate       # Run migrations only
+npm run db:migrate:undo  # Undo last migration
+npm run db:seed          # Seed database only
+npm run db:reset         # Drop, create, migrate, and seed
+```
+
+**Creating new migrations:** Add new migration files deliberately under `backend/src/db/migrations/` only when a schema change is required. Keep them reversible and preserve already applied migration files unchanged.
+
+**Note:** Backend `.env` is loaded centrally by `backend/src/load-env.ts` for app and DB entrypoints. If `NODE_ENV` is absent, it defaults to `dev_stage`, matching the standard VM backend flow and using the `.env` DB settings. Do not add `NODE_ENV=production` to local startup unless a task explicitly requires the production config.
+The backend defaults to port `3000` in `dev_stage` and `8080` otherwise; set `PORT` explicitly when a task needs a different port.
+
+### Frontend (run from `frontend/` directory)
+```bash
+npm install               # Install dependencies
+npm run dev               # Start dev server with Turbopack (port 3001)
+npm run typecheck         # TypeScript check without production build
+npm run verify            # Typecheck, lint, and production build
+npm run build             # Production build
+npm run lint              # ESLint check (.ts, .tsx files)
+npm run format            # Format code with Prettier
+```
+
+### Standard VM Environment
+
+The standard VM port split is:
+- **Frontend PM2 app `frontend-dev`**: Next.js production server on port `3001`
+- **Backend PM2 app `backend-dev`**: `npm run start` with `NODE_ENV=dev_stage` on port `3000`
+- **Apache**: public entrypoint and reverse proxy on port `80`
+
+Direct VM backend health checks should target `http://127.0.0.1:3000/api/...`. A protected endpoint returning `401 Unauthorized` without JWT means the backend is reachable.
+
+### Docker (run from `docker/` directory)
+```bash
+chmod +x start-backend.sh && chmod +x wait-for-it.sh  # First time setup
+docker-compose up                                       # Start all services
+rm -rf data && docker-compose up                        # Start with fresh database
+```
+
+## Architecture
+
+### Backend Structure (`backend/src/`)
+- **routes/**: Express route handlers (RESTful endpoints)
+- **db/api/**: Database access layer (CRUD operations per model)
+- **db/models/**: Sequelize model definitions
+- **db/migrations/**: Database migrations
+- **db/seeders/**: Seed data
+- **auth/**: Passport.js authentication (JWT, Google OAuth, Microsoft OAuth)
+- **services/**: Business logic services (emails, notifications, publishing, file storage)
+- **factories/**: Router and service generation (`router.factory.js`, `service.factory.js`)
+- **middlewares/**: Permission checking, runtime context handling
+- **helpers/**: Utility functions (e.g., `wrapAsync` for async error handling)
+
+### Frontend Structure (`frontend/src/`)
+- **pages/**: Next.js pages (each entity has `-list`, `-edit`, `-new`, `-view`, `-table` variants)
+- **components/**: React components (PascalCase naming)
+- **stores/**: Redux Toolkit slices (per entity + auth, main, style slices)
+- **layouts/**: Page layouts (Authenticated, Guest)
+- **hooks/**: Global custom hooks (`usePreloadOrchestrator`, `useNeighborGraph`, etc.)
+- **lib/**: Utility libraries (`elementStyles`, `imagePreDecode`, `mediaDuration`, `parseJson`)
+- **types/**: TypeScript type definitions (`constructor.ts`, `runtime.ts`, `preload.ts`)
+- **helpers/**: Utility functions
+- **styles/**: Global CSS with Tailwind (`_theme.css` uses `@apply`)
+
+### Key Domain Models
+Projects, Tour Pages, Assets, Asset Variants, Permissions, Roles, Users, Publish Events, PWA Caches, Element Type Defaults, Project Element Defaults
+
+**Note:** Page elements, navigation links, and transitions are stored directly in `tour_pages.ui_schema_json`.
+
+### Element Defaults Hierarchy
+The system has a two-level defaults cascade for UI elements:
+1. **element_type_defaults** - Global platform-wide defaults (11 predefined types)
+2. **project_element_defaults** - Project-specific overrides (auto-snapshotted from global on project creation)
+
+When creating new elements, defaults cascade: global → project. Instance-specific settings are stored in `tour_pages.ui_schema_json`.
+
+### Special Pages
+- **`constructor.tsx`**: Tour builder/editor with drag-drop, element positioning, page management
+- **`runtime.tsx`**: Tour playback with transitions, preloading, navigation
+- **`p/[slug].tsx`**: Public tour pages with PWA offline support
+
+### State Management
+- **Redux Toolkit is the default only for client/app state** (auth/session UI, style/theme, layout/sidebar, constructor UI state, app preferences)
+- **TanStack Query is the default for server state** (API reads, entity lists/details, mutations, invalidation, background refetch)
+- Do not create new entity CRUD Redux slices in `stores/[entity]/[entity]Slice.ts`.
+- Core slices: `authSlice.ts` (auth), `mainSlice.ts` (UI), `styleSlice.ts` (theming), `constructorSlice.ts` (editor)
+- Use `useAppSelector` and `useAppDispatch` hooks from `stores/hooks.ts`
+- **Local hooks acceptable** for ephemeral, component-scoped state (e.g., `usePageNavigation` for session-scoped page history)
+- See [stores-module.md](frontend/docs/stores-module.md#state-management-guidelines) for decision tree
+
+## Code Conventions
+
+### Backend
+- ES6+ with arrow functions, const/let
+- Document endpoints with Swagger JSDoc comments
+- Lowercase filenames (e.g., `auth.js`, `projects.js`)
+
+### Frontend
+- Functional components with TypeScript
+- PascalCase for components and types, camelCase for variables/functions
+- Custom hooks prefixed with `use` (e.g., `useAuth`)
+- Tailwind CSS with theme customization in `_theme.css`
+
+### Styling
+- Theme customization uses `@apply` directive in `_theme.css`
+- **Sidebar styles**: Target `#asideMenu` (defined in `AsideMenuLayer.tsx`) for sidebar overrides
+- Use highly specific selectors when overriding Tailwind utilities to avoid conflicts
+- Themed blocks (`.theme-pink`, `.theme-green`) standardize UI appearance - ensure custom overrides integrate cleanly
+
+### Error Handling
+- Backend: Use centralized `commonErrorHandler` middleware for uniform error responses
+- Frontend: Use React error boundaries for runtime errors
+
+## API Patterns
+
+Routes follow pattern: `/api/[entity]/` with standard CRUD operations
+- `POST /api/auth/signin/local` - Login
+- `GET /api/auth/me` - Current user (requires JWT)
+- Self-registration is disabled. New users are created by Administrator, Platform Owner, or Account Manager through the Users flow and receive an invitation/setup link.
+
+All entity routes support: list, findOne, create, update, destroy operations with pagination and filtering.
+
+## Backend Factory Patterns
+
+### Router Factory (`factories/router.factory.js`)
+Generates standard CRUD routes for entities:
+```javascript
+module.exports = createEntityRouter('assets', AssetsService, AssetsDBApi, {
+  permissionEntity: 'assets',
+});
+```
+
+### Service Factory (`factories/service.factory.js`)
+Generates service classes with transaction handling:
+```javascript
+module.exports = createEntityService('assets', AssetsDBApi);
+```
+
+### Base DB API (`db/api/base.api.js`)
+All entity APIs extend `GenericDBApi` and override:
+- `MODEL` - Sequelize model reference
+- `SEARCHABLE_FIELDS` - Fields for text search
+- `RANGE_FIELDS` - Fields for range filtering
+- `ENUM_FIELDS` - Fields for exact match filtering
+- `getFieldMapping(data)` - Transform input data before save
+
+## File Storage
+
+Controlled by `FILE_STORAGE_PROVIDER` env var or auto-detected from credentials:
+- `s3` - AWS S3 (requires `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`)
+- `gcloud` - Google Cloud Storage
+- `local` - Local filesystem (default)
+
+## Publishing Workflow
+
+Three-tier **content environment** model (distinct from `NODE_ENV` server environment):
+- **Dev** (constructor editing) → **Stage** (preview) → **Production** (public)
+
+**Route-based environment access:**
+- `/p/[slug]` - Production presentation
+- `/p/[slug]/stage` - Stage presentation
+- `/constructor?projectId=` - Dev editing (always dev environment)
+
+Key endpoints:
+- `POST /api/publish/save-to-stage` - Dev → Stage (body: `{ projectId }`)
+- `POST /api/publish` - Stage → Production (body: `{ projectId }`)
+
+**Environment isolation:** Pages have `environment` field (`dev`, `stage`, `production`). The `X-Runtime-Environment` header (set by frontend) determines which content environment to query. Both frontend (`RuntimePresentation.tsx`) and backend (`runtime-context.js`) filter by this field.
+
+**Server Environment vs Content Environment:**
+- `NODE_ENV` controls database config (production/dev_stage/development)
+- `tour_pages.environment` controls content visibility (dev/stage/production)
+
+### Private Production Presentations
+
+Production presentations are public by default at `/p/[slug]`. Each project can switch production runtime visibility through `projects.production_presentation_visibility` (`public` default, `private` optional).
+
+- Platform staff users with any RBAC permission can visit every private production presentation
+- Customer users with `Public` role can visit only private production presentations granted in `production_presentation_access`
+- `Administrator`, `Platform Owner`, and `Account Manager` can create users
+- When creating or editing a `Public` user, the form shows a selector for private production presentations and saves DB access grants
+- Do not use config files or env vars for customer allowlists
+- Do not grant customer viewer users broad permissions such as `READ_PROJECTS` or `READ_TOUR_PAGES`; any RBAC permission makes the user platform staff for private presentation access
+
+See [private-production-presentations.md](documentation/private-production-presentations.md).
+
+## PWA & Offline Support
+
+- **Service Worker**: Generated by Serwist from `frontend/src/sw.ts` → `public/sw.js`
+- **Offline Caching**: PWA_Caches model tracks cached assets per project
+- **Runtime Mode**: Middleware distinguishes public vs authenticated access for offline tours
+
+## Asset Preloading Architecture
+
+Runtime presentations use direct S3 downloads via presigned URLs for instant page navigation:
+
+```
+1. Request presigned URLs (max 50 per batch, 1-hour expiry)
+   POST /api/file/presign { urls: ["assets/img.jpg", ...] }
+
+2. Download directly from S3 → Store in Cache API (< 5MB) or IndexedDB (≥ 5MB)
+
+3. Create blob URL → Decode image → Store in readyBlobUrlsRef
+
+4. Instant lookup during navigation (O(1))
+   const blobUrl = preloadOrchestrator.getReadyBlobUrl(originalUrl);
+```
+
+**Preload Priority:** Transition videos (+150) > Images (+100) > Audio (+50) > Video (+30)
+
+**Storage Layers:**
+| Layer | Size Limit | Purpose |
+|-------|------------|---------|
+| Cache API | < 5MB | Fast asset storage |
+| IndexedDB (Dexie) | ≥ 5MB | Large assets, offline data |
+| Blob URLs | Memory | Pre-decoded for instant display |
+
+## Frontend Patterns
+
+### MUI X Data Grid v7
+Use new `valueGetter` signature:
+```typescript
+// For value transformation
+valueGetter: (value) => value?.id ?? value
+
+// For row access
+valueGetter: (_value, row) => new Date(row.created_at)
+```
+
+### Custom Hooks
+Hooks are located in three places:
+- **`src/hooks/`**: Global hooks (`usePreloadOrchestrator`, `usePageNavigationState`, `useTransitionPlayback`, `usePageNavigation`)
+- **`src/hooks/video/`**: Video playback primitives (8 composable hooks for video playback scenarios)
+- **Component directories**: Domain-specific hooks (`components/Assets/useAssetUploader.ts`)
+
+Key runtime hooks:
+| Hook | Purpose |
+|------|---------|
+| `usePreloadOrchestrator` | Stream-first asset preloading (current page + transitions only) |
+| `usePageNavigationState` | Unified navigation state machine (replaces 6+ hooks) |
+| `useTransitionPlayback` | Video transition playback coordination |
+| `usePageNavigation` | Page history tracking with browser-like back behavior |
+| `useCanvasScale` | Responsive canvas scaling with letterbox mode |
+| `useNetworkAware` | Network condition monitoring for adaptive transitions |
+| `useBackgroundDimensionSuggestion` | Detect background media dimensions for canvas size suggestions |
+
+**Video Hooks (`src/hooks/video/`):**
+| Hook | Purpose |
+|------|---------|
+| `useVideoBlobUrl` | Resolve video URLs to blob URLs from preload cache |
+| `useVideoPlaybackCore` | Core playback logic combining multiple primitives |
+| `useVideoPlayer` | Complete UI video player hook |
+
+### Redux Entity Pattern
+Use this pattern only when maintaining an existing Redux entity flow; new server-state code should use TanStack Query hooks instead.
+```typescript
+import { fetch, deleteItem } from '../../stores/assets/assetsSlice';
+const dispatch = useAppDispatch();
+dispatch(fetch({ query: '?limit=100' }));
+```
+
+## Feature Documentation
+
+Detailed feature documentation is available in `documentation/`:
+
+| Document | Description |
+|----------|-------------|
+| [project-architecture.md](documentation/project-architecture.md) | Overall project structure and architecture |
+| [api-reference.md](documentation/api-reference.md) | API endpoints reference |
+| [authentication-system.md](documentation/authentication-system.md) | JWT, OAuth (Google, Microsoft) authentication |
+| [rbac-system.md](documentation/rbac-system.md) | Role-based access control system |
+| [user-management.md](documentation/user-management.md) | User CRUD, roles assignment, account management |
+| [project-memberships.md](documentation/project-memberships.md) | Team collaboration, per-project access control |
+| [asset-upload-variants.md](documentation/asset-upload-variants.md) | Asset upload pipeline and variant generation |
+| [ui-elements.md](documentation/ui-elements.md) | UI Elements stored in `ui_schema_json` (buttons, hotspots, galleries, tooltips, media players) |
+| [page-transitions.md](documentation/page-transitions.md) | Video transitions stored on navigation elements |
+| [project-transition-settings.md](documentation/project-transition-settings.md) | Environment-aware CSS transition settings (fade, duration, easing) |
+| [video-playback.md](documentation/video-playback.md) | Video player implementation, iOS autoplay compatibility |
+| [assets-preloading.md](documentation/assets-preloading.md) | Asset preloading and caching strategy |
+| [publishing-workflow.md](documentation/publishing-workflow.md) | Dev → Stage → Production publishing |
+| [private-production-presentations.md](documentation/private-production-presentations.md) | Private production presentation allowlist, viewer users, and runtime access flow |
+| [offline-pwa-mode.md](documentation/offline-pwa-mode.md) | PWA offline capabilities and caching |
+| [email-notification-service.md](documentation/email-notification-service.md) | Nodemailer/SES integration, verification emails, invitations |
+| [search-system.md](documentation/search-system.md) | Global full-text search, permission-based filtering |
+| [deployment-vm.md](documentation/deployment-vm.md) | Standard VM deployment topology, PM2 recovery, ports, OOM/ffmpeg diagnostics |
+| [custom-domains-apache.md](documentation/custom-domains-apache.md) | Customer-owned presentation domains via Apache, DNS A records, Certbot, and host/path routing |
+| [page-links-navigation.md](documentation/page-links-navigation.md) | Page navigation using `targetPageSlug` in elements |
+| [access-logs-audit-trail.md](documentation/access-logs-audit-trail.md) | Access logging, audit trail, activity tracking |
+| [db-cleanup-audit.md](documentation/db-cleanup-audit.md) | Non-destructive DB cleanup audit, orphan checks, legacy schema checks, and soft-delete retention policy |
+| [global-ui-controls.md](documentation/global-ui-controls.md) | Configurable fullscreen, sound, and offline system controls with global/project/page cascade |
+| [backend/database-schema.md](backend/docs/database-schema.md) | Complete database schema - all models, fields, relationships, indexes, constraints |
+| [backend/backend-architecture.md](backend/docs/backend-architecture.md) | Backend architecture - layers, design patterns, middleware, factories, file storage |
+| [backend/api-endpoints.md](backend/docs/api-endpoints.md) | Complete API reference - all endpoints, request/response formats, authentication, rate limits |
+| [backend/modules/core.md](backend/docs/modules/core.md) | Core module - index.js (entry), config.ts (configuration), helpers.js/utilities |
+| [backend/modules/auth.md](backend/docs/modules/auth.md) | Auth module - Passport.js strategies (JWT, Google, Microsoft), login, invitation setup, password reset, email verification |
+| [backend/modules/middleware.md](backend/docs/modules/middleware.md) | Middleware module - rate limiting, permissions, runtime context, public access control, file uploads |
+| [backend/modules/routes.md](backend/docs/modules/routes.md) | Routes module - 22 route files, factory pattern, CRUD endpoints, Swagger docs, auth/file/search/sql routes |
+| [backend/modules/services.md](backend/docs/modules/services.md) | Services module - business logic layer, 34 service files, factory pattern, file storage (S3/GCloud/Local), email, notifications, publishing |
+| [backend/modules/email.md](backend/docs/modules/email.md) | Email module - Nodemailer/AWS SES, transactional emails, HTML templates, token management, email verification, password reset, invitations |
+| [backend/modules/notifications.md](backend/docs/modules/notifications.md) | Notifications module - error classes (ValidationError, ForbiddenError), i18n message catalog, helper functions |
+| [backend/modules/factories.md](backend/docs/modules/factories.md) | Factories module - createEntityRouter and createEntityService functions, code generation patterns for CRUD operations, boilerplate elimination |
+| [backend/modules/db-models.md](backend/docs/modules/db-models.md) | DB Models module - 16 Sequelize models, entity definitions, associations, validations, lifecycle hooks, soft delete patterns |
+| [backend/modules/db-api.md](backend/docs/modules/db-api.md) | DB API module - GenericDBApi base class, 18 entity APIs, declarative configuration, query filtering, runtime context helpers |
+| [backend/modules/db-migrations.md](backend/docs/modules/db-migrations.md) | DB Migrations module - Umzug runner, migration safety rules, schema evolution, data backfill |
+| [backend/modules/db-seeders.md](backend/docs/modules/db-seeders.md) | DB Seeders module - Umzug seeders, RBAC setup (7 roles, 54 permissions), sample data opt-in |
+| [backend/modules/db-config.md](backend/docs/modules/db-config.md) | DB Config module - typed DB config, environment validation (Joi), Umzug commands, sync/reset scripts |
+| [backend/modules/utilities.md](backend/docs/modules/utilities.md) | Utilities module - error classes, Pino logging, env validation, request helpers (wrapAsync, commonErrorHandler), DB utils, i18n messages |
+| [backend/testing.md](backend/docs/testing.md) | Backend test strategy - unit, integration, and e2e coverage, helpers, commands, and environment notes |
+| [frontend/hooks-reference.md](frontend/docs/hooks-reference.md) | React hooks reference (useFormSync, useEntityTable, useOfflineMode, etc.) |
+| [frontend/video-hooks-module.md](frontend/docs/video-hooks-module.md) | Video playback primitive hooks (8 composable hooks for video scenarios) |
+| [frontend/constructor-page-editor.md](frontend/docs/constructor-page-editor.md) | Constructor page editor - visual tour builder with drag-drop elements |
+| [frontend/runtime-presentation.md](frontend/docs/runtime-presentation.md) | Runtime presentation viewer - full-screen tour playback with transitions |
+| [frontend/navigation-smooth-transitions.md](frontend/docs/navigation-smooth-transitions.md) | Navigation & smooth transitions - page switching, transition video playback, last frame preservation, online/offline modes |
+| [frontend/ui-adaptivity-system.md](frontend/docs/ui-adaptivity-system.md) | UI Adaptivity System - canvas units (--cu), responsive scaling, letterbox mode, element styling |
+| [frontend/ui-element-preloading-analysis.md](frontend/docs/ui-element-preloading-analysis.md) | UI element processing & neighbor preloading - deep analysis of asset extraction, preload flow, offline caching |
+| [frontend/asset-upload-preloading-pwa-analysis.md](frontend/docs/asset-upload-preloading-pwa-analysis.md) | Deep analysis of asset upload, preload orchestrator, PWA/offline mode, storage layers, network awareness |
+| [frontend/frontend-architecture.md](frontend/docs/frontend-architecture.md) | Frontend architecture - 386 files, 14 modules, factories, hooks, Redux, PWA/offline, design patterns |
+| [frontend/pages-module.md](frontend/docs/pages-module.md) | Pages module - 99 pages, _app.tsx entry, entity CRUD pattern, constructor, runtime presentations, layouts |
+| [frontend/components-module.md](frontend/docs/components-module.md) | Components module - 183 files, entity tables, factories, constructor, element settings, runtime, PWA/offline |
+| [frontend/hooks-module.md](frontend/docs/hooks-module.md) | Hooks module - 52 custom hooks, runtime/preloading, PWA/offline, constructor, tables/forms, UI utilities |
+| [frontend/stores-module.md](frontend/docs/stores-module.md) | Stores module - Redux Toolkit, 17 slices (4 core + 13 entity), createEntitySlice factory, typed hooks |
+| [frontend/lib-module.md](frontend/docs/lib-module.md) | Lib module - 19 utility files, asset URL management, element defaults/styles/effects, offline storage (Cache API + IndexedDB), download queue |
+| [frontend/types-module.md](frontend/docs/types-module.md) | Types module - 18 TypeScript definition files, entity types, constructor/runtime types, API/Redux types, permissions enum, offline/preload types |
+| [frontend/factories-module.md](frontend/docs/factories-module.md) | Factories module - 5 factory files (~1,285 LOC), createListPage, createFormPage, createTableComponent, configBuilderFactory, createEntitySlice for 91% boilerplate reduction |
+| [frontend/schemas-module.md](frontend/docs/schemas-module.md) | Schemas module - 6 Zod validation schema files (~257 LOC), form validation for User, Asset, Project, TourPage, Role entities with type inference |
+| [frontend/helpers-module.md](frontend/docs/helpers-module.md) | Helpers module - 6 utility files (~304 LOC), dataFormatter (entity display), hasPermission (RBAC), notifyStateHandler (Redux), text formatters, file saver |
+| [frontend/layouts-module.md](frontend/docs/layouts-module.md) | Layouts module - 2 layout files (~262 LOC), LayoutAuthenticated (JWT auth, permissions, UI chrome), LayoutGuest (public pages), getLayout pattern |
+| [frontend/config-module.md](frontend/docs/config-module.md) | Config module - 12 config files (~523 LOC), Next.js/Tailwind/TypeScript build config, runtime settings (config.ts), menu configs, offline/preload configs, ESLint rules |
+| [frontend/context-module.md](frontend/docs/context-module.md) | Context module - DownloadContext (~256 LOC) for PWA download progress state, DownloadEventBus integration, useDownloadContext/useDownloadContextOptional hooks |
+| [frontend/interfaces-module.md](frontend/docs/interfaces-module.md) | Interfaces module - ~15 type definition files (~2,200+ LOC), entity types, API contracts, Redux state shapes, permissions enum, constructor/runtime/offline/preload interfaces |
diff --git a/README.md b/README.md
index d8dbe87..c418752 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,15 @@ After seeding, use the credentials configured in backend environment/config valu
     └── README.md            # Docker documentation
 ```
 
+## Documentation
+
+- [General feature documentation](documentation/project-architecture.md) - platform architecture and cross-cutting features
+- [API reference](documentation/api-reference.md) - public API overview and workflow-level endpoint notes
+- [Backend documentation](backend/docs/backend-architecture.md) - backend architecture, modules, database, and tests
+- [Backend API endpoints](backend/docs/api-endpoints.md) - backend endpoint reference
+- [Frontend documentation](frontend/docs/frontend-architecture.md) - frontend architecture, pages, components, hooks, and runtime flows
+- [VM deployment](documentation/deployment-vm.md) - standard VM topology, ports, PM2, Apache, and diagnostics
+
 ## Key Workflows
 
 ### Tour Creation
diff --git a/backend/README.md b/backend/README.md
index 0227a86..8bdc4f5 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -53,6 +53,15 @@ npm run check:public-access
   non-Public private production presentation grants. Review its output before
   running `npm run fix:public-access`.
 
+## Documentation
+
+- [Backend architecture](docs/backend-architecture.md) - service boundaries, app bootstrap, middleware, and factories
+- [API endpoints](docs/api-endpoints.md) - backend REST API reference
+- [Database schema](docs/database-schema.md) - models, relationships, indexes, and constraints
+- [Testing strategy](docs/testing.md) - unit, integration, and e2e test notes
+- [Backend modules](docs/modules/core.md) - module-level documentation entry point
+- [VM deployment](../documentation/deployment-vm.md) - standard VM ports, PM2, Apache, and backend health checks
+
 ## Environment Variables
 
 Create a `.env` file in the backend directory:
diff --git a/backend/docs/api-endpoints.md b/backend/docs/api-endpoints.md
new file mode 100644
index 0000000..f3357b9
--- /dev/null
+++ b/backend/docs/api-endpoints.md
@@ -0,0 +1,1671 @@
+# Backend API Endpoints Documentation
+
+Complete reference for all API endpoints in the Tour Builder Platform backend.
+
+## Overview
+
+- **Base URL**: `http://localhost:3000/api` for local development
+- **Content-Type**: `application/json`
+- **Authentication**: JWT Bearer Token (except public endpoints)
+- **API Documentation UI**: `http://localhost:3000/api-docs` (Swagger, local development)
+
+**Standard VM note:** the VM `dev_stage` backend listens on port `3000`, while
+the frontend listens on `3001` and Apache serves the public domain on port `80`.
+Use `http://127.0.0.1:3000/api/...` for direct VM backend checks. Protected
+routes returning `401 Unauthorized` without JWT are healthy. See
+[`deployment-vm.md`](../../documentation/deployment-vm.md).
+
+---
+
+## Table of Contents
+
+1. [Authentication](#1-authentication)
+2. [Health & System](#2-health--system)
+3. [Users](#3-users)
+4. [Roles](#4-roles)
+5. [Permissions](#5-permissions)
+6. [Projects](#6-projects)
+7. [Project Memberships](#7-project-memberships)
+8. [Tour Pages](#8-tour-pages)
+9. [Assets](#9-assets)
+10. [Asset Variants](#10-asset-variants)
+11. [Project Audio Tracks](#11-project-audio-tracks)
+12. [Project Transition Settings](#12-project-transition-settings)
+13. [Global UI Controls](#13-global-ui-controls)
+14. [Element Defaults](#14-element-defaults)
+15. [Publishing](#15-publishing)
+16. [File Management](#16-file-management)
+17. [Search](#17-search)
+20. [Access Logs](#20-access-logs)
+21. [Publish Events](#21-publish-events)
+22. [PWA Caches](#22-pwa-caches)
+23. [Presigned URL Requests](#23-presigned-url-requests)
+
+---
+
+## Common Patterns
+
+### Authentication Header
+
+```http
+Authorization: Bearer <jwt_token>
+```
+
+### Query Parameters (List Endpoints)
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `page` | number | Page number (0-indexed) |
+| `limit` | number | Items per page (default: 10) |
+| `field` | string | Field to sort by |
+| `sort` | string | Sort direction: `asc` or `desc` |
+| `filetype` | string | Set to `csv` for CSV export |
+| `<field>` | string | Text search filter (ILIKE) |
+| `<field>Range` | string | Range filter: `[min,max]` |
+
+### Standard List Response
+
+```json
+{
+  "rows": [...],
+  "count": 100
+}
+```
+
+### Rate Limits
+
+| Endpoint Type | Limit | Window |
+|---------------|-------|--------|
+| Auth | 10 requests | 15 minutes |
+| Signup | 5 requests | 1 hour |
+| Password Reset | 5 requests | 1 hour |
+| API (general) | 100 requests | 1 minute |
+| Upload | 10 requests | 1 minute |
+| Download | 200 requests | 1 minute |
+| Search | 30 requests | 1 minute |
+| AI | 20 requests | 1 minute |
+
+### Rate Limit Headers
+
+```http
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 99
+X-RateLimit-Reset: 2026-03-30T12:00:00.000Z
+Retry-After: 60  # (only on 429)
+```
+
+---
+
+## 1. Authentication
+
+### POST /api/auth/signin/local
+
+Sign in with email and password.
+
+**Authentication**: None
+**Rate Limit**: 10/15min
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+```
+
+**Response (200):**
+```json
+"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+**Errors:**
+- `400`: Invalid credentials
+
+---
+
+### Self-Registration
+
+Self-registration is disabled. `POST /api/auth/signup` is not registered.
+New users are created through the authenticated Users API/UI and receive an
+invitation/setup link.
+
+---
+
+### GET /api/auth/me
+
+Get current authenticated user.
+
+**Authentication**: Required
+
+**Response (200):**
+```json
+{
+  "id": "uuid",
+  "email": "user@example.com",
+  "firstName": "John",
+  "lastName": "Doe",
+  "phoneNumber": "+1234567890",
+  "emailVerified": true,
+  "disabled": false,
+  "app_role": {
+    "id": "uuid",
+    "name": "User",
+    "globalAccess": false
+  },
+  "custom_permissions": []
+}
+```
+
+---
+
+### PUT /api/auth/password-reset
+
+Reset password using token.
+
+**Authentication**: None
+
+**Request:**
+```json
+{
+  "token": "reset-token-from-email",
+  "password": "newPassword123"
+}
+```
+
+**Response (200):** `true`
+
+---
+
+### POST /api/auth/send-password-reset-email
+
+Send password reset email.
+
+**Authentication**: None
+**Rate Limit**: 5/hour
+
+**Request:**
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+**Response (200):** `true`
+
+---
+
+### PUT /api/auth/password-update
+
+Update password for authenticated user.
+
+**Authentication**: Required
+
+**Request:**
+```json
+{
+  "currentPassword": "oldPassword",
+  "newPassword": "newPassword123"
+}
+```
+
+**Response (200):** `true`
+
+---
+
+### PUT /api/auth/profile
+
+Update user profile.
+
+**Authentication**: Required
+
+**Request:**
+```json
+{
+  "profile": {
+    "firstName": "John",
+    "lastName": "Doe",
+    "phoneNumber": "+1234567890"
+  }
+}
+```
+
+**Response (200):** `true`
+
+---
+
+### PUT /api/auth/verify-email
+
+Verify email address.
+
+**Authentication**: None
+
+**Request:**
+```json
+{
+  "token": "verification-token-from-email"
+}
+```
+
+**Response (200):** JWT token
+
+---
+
+### GET /api/auth/email-configured
+
+Check if email service is configured.
+
+**Authentication**: None
+
+**Response (200):** `true` or `false`
+
+---
+
+### GET /api/auth/signin/google
+
+Initiate Google OAuth flow.
+
+**Authentication**: None
+
+**Query Parameters:**
+- `app`: Optional state parameter
+
+**Response**: Redirect to Google
+
+---
+
+### GET /api/auth/signin/google/callback
+
+Google OAuth callback.
+
+**Response**: Redirect to frontend with token
+
+---
+
+### GET /api/auth/signin/microsoft
+
+Initiate Microsoft OAuth flow.
+
+**Authentication**: None
+
+**Response**: Redirect to Microsoft
+
+---
+
+### GET /api/auth/signin/microsoft/callback
+
+Microsoft OAuth callback.
+
+**Response**: Redirect to frontend with token
+
+---
+
+## 2. Health & System
+
+### GET /api/health
+
+Health check endpoint.
+
+**Authentication**: None
+
+**Response (200):**
+```json
+{
+  "status": "ok",
+  "timestamp": "2026-03-30T12:00:00.000Z",
+  "uptime": 12345.678,
+  "environment": "production",
+  "database": "connected"
+}
+```
+
+**Response (503):** (when database is down)
+```json
+{
+  "status": "degraded",
+  "timestamp": "2026-03-30T12:00:00.000Z",
+  "uptime": 12345.678,
+  "environment": "production",
+  "database": "disconnected",
+  "databaseError": "Connection refused"
+}
+```
+
+---
+
+### GET /api/runtime-context
+
+Get current runtime context (environment detection).
+
+**Authentication**: None
+
+**Response (200):**
+```json
+{
+  "mode": "workspace",
+  "projectSlug": "my-project",
+  "headerEnvironment": "production"
+}
+```
+
+---
+
+## 3. Users
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/users` | Create user |
+| GET | `/api/users` | List users |
+| GET | `/api/users/count` | Count users |
+| GET | `/api/users/autocomplete` | Autocomplete search |
+| GET | `/api/users/:id` | Get user by ID |
+| PUT | `/api/users/:id` | Update user |
+| DELETE | `/api/users/:id` | Delete user |
+| POST | `/api/users/deleteByIds` | Bulk delete |
+| POST | `/api/users/bulk-import` | Bulk import |
+
+**Authentication**: Required
+**Permissions**: `CREATE_USERS`, `READ_USERS`, `UPDATE_USERS`, `DELETE_USERS`
+
+### POST /api/users
+
+**Request:**
+```json
+{
+  "data": {
+    "firstName": "John",
+    "lastName": "Doe",
+    "email": "john@example.com",
+    "phoneNumber": "+1234567890",
+    "app_role": "uuid-of-role",
+    "custom_permissions": ["uuid-1", "uuid-2"],
+    "password": "password123",
+    "disabled": false
+  }
+}
+```
+
+---
+
+### GET /api/users
+
+**Query Parameters:**
+- `firstName`: Filter by first name
+- `lastName`: Filter by last name
+- `email`: Filter by email
+- `app_role`: Filter by role ID
+- Standard pagination params
+
+**Response:**
+```json
+{
+  "rows": [
+    {
+      "id": "uuid",
+      "firstName": "John",
+      "lastName": "Doe",
+      "email": "john@example.com",
+      "phoneNumber": "+1234567890",
+      "disabled": false,
+      "emailVerified": true,
+      "app_role": { "id": "uuid", "name": "User" }
+    }
+  ],
+  "count": 1
+}
+```
+
+---
+
+## 4. Roles
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/roles` | Create role |
+| GET | `/api/roles` | List roles |
+| GET | `/api/roles/count` | Count roles |
+| GET | `/api/roles/autocomplete` | Autocomplete search |
+| GET | `/api/roles/:id` | Get role by ID |
+| PUT | `/api/roles/:id` | Update role |
+| DELETE | `/api/roles/:id` | Delete role |
+| POST | `/api/roles/deleteByIds` | Bulk delete |
+
+**Permissions**: `CREATE_ROLES`, `READ_ROLES`, `UPDATE_ROLES`, `DELETE_ROLES`
+
+### POST /api/roles
+
+**Request:**
+```json
+{
+  "data": {
+    "name": "Editor",
+    "globalAccess": false,
+    "permissions": ["uuid-1", "uuid-2"]
+  }
+}
+```
+
+---
+
+## 5. Permissions
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/permissions` | Create permission |
+| GET | `/api/permissions` | List permissions |
+| GET | `/api/permissions/count` | Count permissions |
+| GET | `/api/permissions/autocomplete` | Autocomplete search |
+| GET | `/api/permissions/:id` | Get permission by ID |
+| PUT | `/api/permissions/:id` | Update permission |
+| DELETE | `/api/permissions/:id` | Delete permission |
+| POST | `/api/permissions/deleteByIds` | Bulk delete |
+
+**Permissions**: `CREATE_PERMISSIONS`, `READ_PERMISSIONS`, `UPDATE_PERMISSIONS`, `DELETE_PERMISSIONS`
+
+### POST /api/permissions
+
+**Request:**
+```json
+{
+  "data": {
+    "name": "READ_CUSTOM_FEATURE"
+  }
+}
+```
+
+---
+
+## 6. Projects
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/projects` | Create project |
+| GET | `/api/projects` | List projects |
+| GET | `/api/projects/count` | Count projects |
+| GET | `/api/projects/autocomplete` | Autocomplete search |
+| GET | `/api/projects/:id` | Get project by ID |
+| PUT | `/api/projects/:id` | Update project |
+| DELETE | `/api/projects/:id` | Delete project |
+| POST | `/api/projects/deleteByIds` | Bulk delete |
+
+**Permissions**: `CREATE_PROJECTS`, `READ_PROJECTS`, `UPDATE_PROJECTS`, `DELETE_PROJECTS`
+
+**Runtime Public Access**: GET endpoints accessible without auth in production mode.
+
+### POST /api/projects
+
+**Request:**
+```json
+{
+  "data": {
+    "name": "My Tour",
+    "slug": "my-tour",
+    "description": "A virtual tour of the museum",
+    "logo_url": "assets/logo.png",
+    "favicon_url": "assets/favicon.ico",
+    "og_image_url": "assets/og-image.jpg"
+  }
+}
+```
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Project display name |
+| `slug` | string | URL-safe identifier (auto-generated if not provided) |
+| `description` | string | Project description |
+| `logo_url` | string | Path to project logo |
+| `favicon_url` | string | Path to favicon |
+| `og_image_url` | string | Path to Open Graph image |
+
+---
+
+### POST /api/projects/:id/clone
+
+Clone an existing project with all pages and settings.
+
+**Request:** None (uses URL parameter)
+
+**Response:**
+```json
+{
+  "id": "new-project-uuid",
+  "name": "My Tour (Copy)",
+  "slug": "my-tour-copy"
+}
+```
+
+---
+
+### GET /api/projects/:id/offline-manifest
+
+Get PWA offline manifest for a project.
+
+**Query Parameters:**
+- `variant`: `mobile` or `desktop` (default: `desktop`)
+
+**Response:**
+```json
+{
+  "projectId": "uuid",
+  "version": "2026-03-30T12:00:00.000Z",
+  "assets": [
+    {
+      "url": "assets/image.jpg",
+      "type": "image",
+      "size": 1024000
+    }
+  ],
+  "pages": [
+    {
+      "slug": "home",
+      "name": "Home Page"
+    }
+  ]
+}
+```
+
+---
+
+## 7. Project Memberships
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/project_memberships` | Create membership |
+| GET | `/api/project_memberships` | List memberships |
+| GET | `/api/project_memberships/count` | Count memberships |
+| GET | `/api/project_memberships/:id` | Get membership by ID |
+| PUT | `/api/project_memberships/:id` | Update membership |
+| DELETE | `/api/project_memberships/:id` | Delete membership |
+
+**Permissions**: `CREATE_PROJECT_MEMBERSHIPS`, `READ_PROJECT_MEMBERSHIPS`, etc.
+
+### POST /api/project_memberships
+
+**Request:**
+```json
+{
+  "data": {
+    "user": "user-uuid",
+    "project": "project-uuid",
+    "membershipRole": "editor"
+  }
+}
+```
+
+**Membership Roles:**
+- `owner` - Full access including delete
+- `editor` - Can edit content
+- `viewer` - Read-only access
+
+---
+
+## 8. Tour Pages
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/tour_pages` | Create page |
+| GET | `/api/tour_pages` | List pages |
+| GET | `/api/tour_pages/count` | Count pages |
+| GET | `/api/tour_pages/:id` | Get page by ID |
+| PUT | `/api/tour_pages/:id` | Update page |
+| DELETE | `/api/tour_pages/:id` | Delete page |
+| POST | `/api/tour_pages/deleteByIds` | Bulk delete |
+| POST | `/api/tour_pages/reorder` | Reorder pages by updating `sort_order` only |
+| POST | `/api/tour_pages/:id/duplicate` | Duplicate a dev page as a new independent dev page |
+
+**Permissions**: `CREATE_TOUR_PAGES`, `READ_TOUR_PAGES`, etc.
+
+**Runtime Public Access**: GET endpoints accessible without auth in production mode.
+
+### POST /api/tour_pages/reorder
+
+Reorders pages for a project in the constructor environment.
+
+**Auth:** Required
+
+**Request:**
+
+```json
+{
+  "data": {
+    "projectId": "project-uuid",
+    "environment": "dev",
+    "orderedPageIds": ["page-uuid-1", "page-uuid-2", "page-uuid-3"]
+  }
+}
+```
+
+**Response:**
+
+```json
+[
+  { "id": "page-uuid-1", "sort_order": 1 },
+  { "id": "page-uuid-2", "sort_order": 2 },
+  { "id": "page-uuid-3", "sort_order": 3 }
+]
+```
+
+**Rules:**
+- Only `environment: "dev"` is accepted. Stage and production are updated by
+  publishing, not by direct reorder writes.
+- `orderedPageIds` must include every page in the project/dev environment
+  exactly once.
+- The endpoint updates only `tour_pages.sort_order`; it does not alter
+  `ui_schema_json`, slugs, backgrounds, media, navigation, or transitions.
+- The visible stage order changes after Save to Stage. The visible production
+  order changes after Publish.
+
+**Validation failures:**
+- Missing `projectId`
+- Empty or invalid `orderedPageIds`
+- Duplicate page IDs
+- Missing pages from the ordered list
+- Unknown page IDs or page IDs outside the project/environment
+- Any environment other than `dev`
+
+### POST /api/tour_pages/:id/duplicate
+
+Duplicates a constructor/dev page into a new independent dev page.
+
+**Auth:** Required
+
+**Request:**
+
+```json
+{
+  "data": {
+    "projectId": "project-uuid",
+    "environment": "dev",
+    "name": "Lobby Copy",
+    "slug": "lobby-copy"
+  }
+}
+```
+
+**Rules:**
+- Only source pages in `environment: "dev"` can be duplicated.
+- The requested target environment must also be `dev`.
+- The source page must belong to the requested project.
+- The new page is appended to constructor order with
+  `sort_order = max(project dev sort_order) + 1`.
+- The duplicate receives a new page ID, unique slug, and empty `source_key`.
+- Page settings, background media fields, design dimensions, `requires_auth`,
+  and `ui_schema_json` are copied.
+- Inline `ui_schema_json.elements[]` IDs and nested gallery/carousel/info-panel
+  item IDs are regenerated for independence.
+- Asset URLs, transition URLs, and navigation `targetPageSlug` references are
+  preserved.
+- Reverse-video processing uses the existing `TourPagesService` path.
+
+**Validation failures:**
+- Invalid source page ID
+- Source page not found
+- Source page outside requested project
+- Source or target environment other than `dev`
+
+### POST /api/tour_pages
+
+**Request:**
+```json
+{
+  "data": {
+    "projectId": "project-uuid",
+    "environment": "dev",
+    "name": "Home Page",
+    "slug": "home",
+    "sort_order": 1,
+    "background_image_url": "assets/bg.jpg",
+    "background_video_url": null,
+    "background_audio_url": "assets/ambient.mp3",
+    "background_loop": true,
+    "requires_auth": false,
+    "ui_schema_json": {
+      "elements": [],
+      "canvasSettings": {}
+    }
+  }
+}
+```
+
+**ui_schema_json Structure:**
+```json
+{
+  "elements": [
+    {
+      "id": "element-uuid",
+      "type": "button",
+      "props": {
+        "x": 100,
+        "y": 200,
+        "width": 150,
+        "height": 50,
+        "label": "Click Me",
+        "targetPageSlug": "next-page",
+        "transitionVideo": "assets/transition.mp4"
+      }
+    }
+  ],
+  "canvasSettings": {
+    "width": 1920,
+    "height": 1080
+  }
+}
+```
+
+---
+
+## 9. Assets
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/assets` | Create asset record |
+| GET | `/api/assets` | List assets |
+| GET | `/api/assets/count` | Count assets |
+| GET | `/api/assets/autocomplete` | Autocomplete search |
+| GET | `/api/assets/:id` | Get asset by ID |
+| PUT | `/api/assets/:id` | Update asset |
+| DELETE | `/api/assets/:id` | Delete asset |
+| POST | `/api/assets/deleteByIds` | Bulk delete |
+
+**Permissions**: `CREATE_ASSETS`, `READ_ASSETS`, etc.
+
+### POST /api/assets
+
+Create an asset record with MIME type validation.
+
+**Request:**
+```json
+{
+  "data": {
+    "name": "Hero Image",
+    "asset_type": "image",
+    "type": "background",
+    "cdn_url": "https://cdn.example.com/assets/hero.jpg",
+    "storage_key": "assets/hero.jpg",
+    "mime_type": "image/jpeg",
+    "size_mb": 2.5,
+    "width_px": 1920,
+    "height_px": 1080,
+    "duration_sec": null,
+    "checksum": "abc123...",
+    "is_public": true,
+    "project": "project-uuid"
+  }
+}
+```
+
+**Asset Types:** `image`, `video`, `audio`, `document`, `other`
+
+**Type (Usage):** `background`, `transition`, `element`, `general`
+
+**MIME Type Validation:**
+
+The `mime_type` must match the `asset_type`:
+
+| asset_type | Valid mime_type prefixes |
+|------------|-------------------------|
+| `image` | `image/` (jpeg, png, gif, webp, svg, etc.) |
+| `video` | `video/` (mp4, webm, mov, etc.) |
+| `audio` | `audio/` (mp3, wav, ogg, etc.) |
+
+Other asset types (`document`, `other`, `file`) skip MIME validation.
+
+**Error Response (400):**
+```json
+{
+  "message": "Invalid file type for image. Expected image (jpeg, png, gif, webp, svg, etc.), got \"video/mp4\""
+}
+```
+
+---
+
+## 10. Asset Variants
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/asset_variants` | Create variant |
+| GET | `/api/asset_variants` | List variants |
+| GET | `/api/asset_variants/:id` | Get variant by ID |
+| PUT | `/api/asset_variants/:id` | Update variant |
+| DELETE | `/api/asset_variants/:id` | Delete variant |
+
+**Permissions**: `CREATE_ASSET_VARIANTS`, `READ_ASSET_VARIANTS`, etc.
+
+### POST /api/asset_variants
+
+**Request:**
+```json
+{
+  "data": {
+    "asset": "asset-uuid",
+    "variant_type": "mobile",
+    "cdn_url": "https://cdn.example.com/assets/hero-mobile.jpg",
+    "width_px": 768,
+    "height_px": 432,
+    "size_mb": 0.8
+  }
+}
+```
+
+**Variant Types:** `desktop`, `mobile`, `thumbnail`
+
+---
+
+## 11. Project Audio Tracks
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/project_audio_tracks` | Create audio track |
+| GET | `/api/project_audio_tracks` | List audio tracks |
+| GET | `/api/project_audio_tracks/:id` | Get audio track |
+| PUT | `/api/project_audio_tracks/:id` | Update audio track |
+| DELETE | `/api/project_audio_tracks/:id` | Delete audio track |
+
+**Runtime Public Access**: GET endpoints accessible without auth in production mode.
+
+### POST /api/project_audio_tracks
+
+**Request:**
+```json
+{
+  "data": {
+    "projectId": "project-uuid",
+    "environment": "dev",
+    "name": "Background Music",
+    "slug": "background-music",
+    "url": "assets/music.mp3",
+    "loop": true,
+    "volume": 0.5,
+    "sort_order": 1,
+    "is_enabled": true
+  }
+}
+```
+
+---
+
+## 12. Project Transition Settings
+
+Environment-aware CSS transition settings for page navigation.
+
+### Authentication Model
+
+Uses **URL-path-based public access** - no headers required:
+
+| Endpoint | Method | Environment | Auth Required |
+|----------|--------|-------------|---------------|
+| `/project/:id/env/production` | GET | production | **No** (public) |
+| `/project/:id/env/dev` | GET | dev | JWT + READ_PAGE_ELEMENTS |
+| `/project/:id/env/stage` | GET | stage | JWT + READ_PAGE_ELEMENTS |
+| `/project/:id/env/*` | PUT/DELETE | any | JWT + UPDATE_PAGE_ELEMENTS |
+| Standard CRUD | all | n/a | JWT + PAGE_ELEMENTS CRUD permission |
+
+This allows public presentations (`/p/[slug]`) to fetch production transition settings without authentication in incognito mode.
+
+### Standard CRUD Endpoints (All Require Auth)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/project-transition-settings` | Create settings |
+| GET | `/api/project-transition-settings` | List all settings |
+| GET | `/api/project-transition-settings/:id` | Get by ID |
+| PUT | `/api/project-transition-settings/:id` | Update by ID |
+| DELETE | `/api/project-transition-settings/:id` | Delete by ID |
+
+### Environment-Specific Endpoints
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| GET | `/project/:projectId/env/production` | None | Get production settings (public) |
+| GET | `/project/:projectId/env/dev` | JWT | Get dev settings |
+| GET | `/project/:projectId/env/stage` | JWT | Get stage settings |
+| PUT | `/project/:projectId/env/:environment` | JWT + UPDATE_PAGE_ELEMENTS | Create or update (upsert) |
+| DELETE | `/project/:projectId/env/:environment` | JWT + UPDATE_PAGE_ELEMENTS | Reset settings to global defaults |
+
+### GET /api/project-transition-settings/project/:projectId/env/:environment
+
+**Parameters:**
+- `projectId` (path): Project UUID
+- `environment` (path): `dev`, `stage`, or `production`
+
+**Authentication:**
+- `production`: None required (public access)
+- `dev`/`stage`: `Authorization: Bearer {token}`
+
+**Response (200):**
+```json
+{
+  "id": "uuid",
+  "projectId": "project-uuid",
+  "environment": "production",
+  "transition_type": "fade",
+  "duration_ms": 700,
+  "easing": "ease-in-out",
+  "overlay_color": "#000000",
+  "createdAt": "2026-05-01T12:00:00Z",
+  "updatedAt": "2026-05-01T12:00:00Z"
+}
+```
+
+**Response (200):** `null` when no settings exist (use global/fallback defaults)
+
+**Response (401):** Authentication required (for dev/stage without JWT)
+
+### PUT /api/project-transition-settings/project/:projectId/env/:environment
+
+Creates or updates settings for a project/environment combination.
+
+**Authentication**: Required (JWT + UPDATE_PAGE_ELEMENTS)
+
+**Request:**
+```json
+{
+  "transition_type": "fade",
+  "duration_ms": 1000,
+  "easing": "ease-out",
+  "overlay_color": "#1a1a1a"
+}
+```
+
+**Response (200):** Created or updated settings object
+
+---
+
+## 13. Global UI Controls
+
+Configurable fullscreen, global sound, and offline buttons. Settings cascade
+from global defaults to project/environment overrides and then page overrides.
+
+### Global Defaults
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| GET | `/api/global-ui-control-defaults` | None | Get singleton global UI-control defaults |
+| GET | `/api/global-ui-control-defaults/:id` | None | Get defaults by ID |
+| PUT | `/api/global-ui-control-defaults/:id` | JWT + UPDATE_PAGE_ELEMENTS | Update singleton defaults |
+
+### Project/Environment Overrides
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| GET | `/api/project-ui-control-settings/project/:projectId/env/production` | None or JWT for private production | Get production project overrides |
+| GET | `/api/project-ui-control-settings/project/:projectId/env/dev` | JWT | Get dev project overrides |
+| GET | `/api/project-ui-control-settings/project/:projectId/env/stage` | JWT | Get stage project overrides |
+| PUT | `/api/project-ui-control-settings/project/:projectId/env/:environment` | JWT + UPDATE_PAGE_ELEMENTS | Upsert project overrides |
+| DELETE | `/api/project-ui-control-settings/project/:projectId/env/:environment` | JWT + UPDATE_PAGE_ELEMENTS | Reset project overrides to global defaults |
+
+`production` reads follow private-production presentation rules: public
+presentations are public-readable, private presentations require JWT and an
+allowlist/staff access check.
+
+### Settings JSON
+
+```json
+{
+  "offline": {
+    "enabled": true,
+    "hidden": false,
+    "xPercent": 89.5,
+    "yPercent": 6,
+    "anchor": "center",
+    "buttonSizePercent": 2.6,
+    "iconSizePercent": 1.35,
+    "defaultIconUrl": "",
+    "activeIconUrl": "",
+    "defaultBackgroundColor": "#2563EB",
+    "activeBackgroundColor": "#059669",
+    "hoverBackgroundColor": "#1D4ED8",
+    "color": "#FFFFFF",
+    "defaultBorderColor": "#2563EB",
+    "activeBorderColor": "#059669",
+    "borderRadiusPercent": 0.42,
+    "opacity": 1,
+    "boxShadow": "",
+    "zIndex": 900,
+    "order": 1
+  }
+}
+```
+
+---
+
+## 14. Element Defaults
+
+### Global Transition Defaults
+
+Platform-wide default transition settings (singleton).
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| GET | `/api/global-transition-defaults` | **None** | Get defaults (public) |
+| GET | `/api/global-transition-defaults/:id` | **None** | Get by ID (public) |
+| PUT | `/api/global-transition-defaults/:id` | JWT + UPDATE_PAGE_ELEMENTS | Update defaults |
+
+**Authentication Model**: GET is always public (for runtime presentations), PUT requires JWT.
+
+**GET /api/global-transition-defaults**
+
+```http
+GET /api/global-transition-defaults
+# No authentication required
+```
+
+**Response (200):**
+```json
+{
+  "id": "uuid",
+  "transition_type": "fade",
+  "duration_ms": 700,
+  "easing": "ease-in-out",
+  "overlay_color": "#000000"
+}
+```
+
+**PUT /api/global-transition-defaults/:id**
+
+```http
+PUT /api/global-transition-defaults/:id
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "data": {
+    "transition_type": "fade",
+    "duration_ms": 1000,
+    "easing": "ease-out"
+  }
+}
+```
+
+---
+
+### Element Type Defaults (Global)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/element-type-defaults` | List global defaults |
+| GET | `/api/element-type-defaults/:id` | Get default by ID |
+| PUT | `/api/element-type-defaults/:id` | Update default |
+
+**Alternative Path:** `/api/ui-elements` (backwards compatibility)
+
+**Element Types (11 predefined):**
+- `button`, `hotspot`, `tooltip`, `gallery`
+- `media_player`, `text_block`, `popup`
+- `logo`, `spot`, `hamburger_menu`, `image`
+
+---
+
+### Project Element Defaults
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/project-element-defaults` | List project defaults |
+| GET | `/api/project-element-defaults/:id` | Get default by ID |
+| PUT | `/api/project-element-defaults/:id` | Update default |
+| POST | `/api/project-element-defaults/:id/reset` | Reset to global |
+| GET | `/api/project-element-defaults/:id/diff` | Compare with global |
+
+### POST /api/project-element-defaults/:id/reset
+
+Reset project element default to current global settings.
+
+**Response:**
+```json
+{
+  "id": "uuid",
+  "element_type": "button",
+  "projectId": "project-uuid",
+  "default_props_json": {...}
+}
+```
+
+---
+
+### GET /api/project-element-defaults/:id/diff
+
+Compare project default with global default.
+
+**Response:**
+```json
+{
+  "hasDifferences": true,
+  "projectDefault": {...},
+  "globalDefault": {...},
+  "differences": {
+    "backgroundColor": {
+      "project": "#FF0000",
+      "global": "#0000FF"
+    }
+  }
+}
+```
+
+---
+
+## 15. Publishing
+
+### POST /api/publish
+
+Publish from stage to production.
+
+**Authentication**: Required
+**Permissions**: `CREATE_PUBLISH_EVENTS`
+
+**Request:**
+```json
+{
+  "projectId": "project-uuid",
+  "title": "Version 1.0 Release",
+  "description": "Initial public release with all pages"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "publishEventId": "event-uuid",
+  "summary": {
+    "pages_copied": 10,
+    "audios_copied": 3
+  }
+}
+```
+
+---
+
+### POST /api/publish/save-to-stage
+
+Copy dev content to stage environment.
+
+**Authentication**: Required
+**Permissions**: `CREATE_PUBLISH_EVENTS`
+
+**Request:**
+```json
+{
+  "projectId": "project-uuid"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "publishEventId": "event-uuid",
+  "summary": {
+    "pages_copied": 10,
+    "audios_copied": 3
+  }
+}
+```
+
+**Errors:**
+- `400`: Publish already in progress
+- `404`: Project not found
+
+---
+
+## 16. File Management
+
+### GET /api/file/download
+
+Download a file from storage. Supports automatic client disconnect handling via AbortController.
+
+**Authentication**: None (uses private URL)
+**Rate Limit**: 200/min
+
+**Query Parameters:**
+- `privateUrl`: Storage key (e.g., `assets/image.jpg`)
+
+**Response:** File stream with appropriate Content-Type
+
+**Error Responses:**
+
+| HTTP Status | Condition | S3 Error Types |
+|-------------|-----------|----------------|
+| 400 | Missing privateUrl parameter | - |
+| 401 | Expired credentials | ExpiredToken |
+| 403 | Access denied | AccessDenied, InvalidAccessKeyId |
+| 404 | File not found | NoSuchKey, NotFound, NoSuchBucket |
+| 429 | Rate limited | ThrottlingException |
+| 500 | Internal server error | InternalError |
+| 503 | Service unavailable | NetworkingError, ServiceUnavailable |
+| 504 | Gateway timeout | TimeoutError, RequestTimeout |
+
+**Error Response Format:**
+```json
+{
+  "message": "Could not download the file. NoSuchKey: The specified key does not exist."
+}
+```
+
+**Client Disconnect:** When a client disconnects during download, the backend automatically aborts the S3 request to prevent wasted bandwidth.
+
+---
+
+### POST /api/file/presign
+
+Generate presigned URLs for direct S3 access. Includes path validation to prevent directory traversal attacks.
+
+**Authentication**: None
+**Rate Limit**: 200/min
+
+**Request:**
+```json
+{
+  "urls": [
+    "assets/image1.jpg",
+    "assets/image2.jpg",
+    "assets/video.mp4"
+  ]
+}
+```
+
+**Response:**
+```json
+{
+  "presignedUrls": {
+    "assets/image1.jpg": "https://bucket.s3.amazonaws.com/assets/image1.jpg?...",
+    "assets/image2.jpg": "https://bucket.s3.amazonaws.com/assets/image2.jpg?...",
+    "assets/video.mp4": "https://bucket.s3.amazonaws.com/assets/video.mp4?..."
+  }
+}
+```
+
+**Limits:**
+- Maximum 50 URLs per request
+- Presigned URLs expire in 1 hour (configurable via `AWS_S3_PRESIGN_EXPIRY`)
+
+**Path Validation:**
+URLs are validated to prevent path traversal and ensure security:
+- Must be non-empty strings
+- Must not contain `..` (parent directory traversal)
+- Must not start with `/` (absolute paths)
+- Must not contain null bytes
+
+**Error Responses:**
+
+| HTTP Status | Condition |
+|-------------|-----------|
+| 400 | Missing `urls` array |
+| 400 | `urls` array is empty |
+| 400 | `urls` exceeds maximum of 50 |
+| 400 | Invalid URL format (contains `..`, starts with `/`, etc.) |
+| 500 | S3 presigning failed |
+| 503 | S3 service unavailable |
+
+**Error Response Format:**
+```json
+{
+  "message": "Invalid URL format",
+  "code": "INVALID_PATH",
+  "details": { "invalidUrls": ["../etc/passwd", "/root/secret"] }
+}
+```
+
+---
+
+### POST /api/file/upload/:table/:field
+
+Upload a file (single request).
+
+**Authentication**: Required
+**Rate Limit**: 10/min
+**Content-Type**: `multipart/form-data`
+
+**Form Fields:**
+- `file`: Binary file data
+- `filename`: Target filename
+
+**Response:**
+```json
+{
+  "message": "Uploaded the file successfully: assets/hero.jpg",
+  "url": "https://bucket.s3.amazonaws.com/assets/hero.jpg"
+}
+```
+
+---
+
+### Chunked Upload (Large Files)
+
+For files larger than a few MB, use chunked upload:
+
+#### 1. Initialize Session
+
+**POST /api/file/upload-sessions/init**
+
+**Request:**
+```json
+{
+  "folder": "assets",
+  "filename": "large-video.mp4",
+  "totalChunks": 10,
+  "size": 104857600,
+  "contentType": "video/mp4"
+}
+```
+
+**Response:**
+```json
+{
+  "sessionId": "session-uuid",
+  "uploadedChunks": [],
+  "totalChunks": 10
+}
+```
+
+---
+
+#### 2. Upload Chunks
+
+**PUT /api/file/upload-sessions/:sessionId/chunks/:chunkIndex**
+
+**Content-Type**: `application/octet-stream`
+**Body**: Raw binary chunk data
+
+**Response:**
+```json
+{
+  "sessionId": "session-uuid",
+  "chunkIndex": 0,
+  "uploadedChunks": 1,
+  "totalChunks": 10
+}
+```
+
+---
+
+#### 3. Check Session Status
+
+**GET /api/file/upload-sessions/:sessionId**
+
+**Response:**
+```json
+{
+  "sessionId": "session-uuid",
+  "totalChunks": 10,
+  "uploadedChunks": [0, 1, 2, 3, 4],
+  "status": "uploading"
+}
+```
+
+---
+
+#### 4. Finalize Upload
+
+**POST /api/file/upload-sessions/:sessionId/finalize**
+
+**Response:**
+```json
+{
+  "message": "Uploaded the file successfully: assets/large-video.mp4",
+  "privateUrl": "assets/large-video.mp4",
+  "url": "https://bucket.s3.amazonaws.com/assets/large-video.mp4"
+}
+```
+
+---
+
+## 17. Search
+
+### POST /api/search
+
+Global full-text search across entities.
+
+**Authentication**: Required
+**Rate Limit**: 30/min
+**Permissions**: `READ_SEARCH` (implicit via entity permissions)
+
+**Request:**
+```json
+{
+  "searchQuery": "museum"
+}
+```
+
+**Response:**
+```json
+[
+  {
+    "id": "uuid",
+    "name": "Museum Tour",
+    "tableName": "projects",
+    "matchAttribute": ["name", "description"]
+  },
+  {
+    "id": "uuid",
+    "slug": "museum-entrance",
+    "tableName": "tour_pages",
+    "matchAttribute": ["slug"]
+  }
+]
+```
+
+**Searchable Tables:**
+
+| Table | Text Fields | Numeric Fields |
+|-------|-------------|----------------|
+| `users` | firstName, lastName, phoneNumber, email | - |
+| `projects` | name, slug, description, logo_url, favicon_url, og_image_url | - |
+| `assets` | name, cdn_url, storage_key, mime_type, checksum | size_mb, width_px, height_px, duration_sec |
+| `asset_variants` | cdn_url | width_px, height_px, size_mb |
+| `presigned_url_requests` | requested_key, mime_type, status | requested_size_mb |
+| `tour_pages` | source_key, name, slug, background_image_url, background_video_url, background_audio_url, ui_schema_json | sort_order |
+| `project_audio_tracks` | source_key, name, slug, url | volume, sort_order |
+| `publish_events` | error_message | pages_copied, transitions_copied, audios_copied |
+| `pwa_caches` | cache_version, manifest_json, asset_list_json | - |
+| `access_logs` | path, ip_address, user_agent | - |
+
+---
+
+## 20. Access Logs
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/access_logs` | List access logs |
+| GET | `/api/access_logs/count` | Count access logs |
+| GET | `/api/access_logs/:id` | Get access log by ID |
+
+**Permissions**: `READ_ACCESS_LOGS`
+
+### GET /api/access_logs
+
+**Query Parameters:**
+- `path`: Filter by path
+- `ip_address`: Filter by IP
+- `user_agent`: Filter by user agent
+- Standard pagination params
+
+**Response:**
+```json
+{
+  "rows": [
+    {
+      "id": "uuid",
+      "path": "/p/my-tour/",
+      "ip_address": "192.168.1.1",
+      "user_agent": "Mozilla/5.0...",
+      "project": { "id": "uuid", "name": "My Tour" },
+      "createdAt": "2026-03-30T12:00:00.000Z"
+    }
+  ],
+  "count": 100
+}
+```
+
+---
+
+## 21. Publish Events
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/publish_events` | List publish events |
+| GET | `/api/publish_events/count` | Count publish events |
+| GET | `/api/publish_events/:id` | Get publish event by ID |
+
+**Permissions**: `READ_PUBLISH_EVENTS`
+
+### GET /api/publish_events
+
+**Query Parameters:**
+- `project`: Filter by project ID
+- `status`: Filter by status (queued, running, success, failed)
+- `from_environment`: Filter by source (dev, stage)
+- `to_environment`: Filter by target (stage, production)
+- Standard pagination params
+
+**Response:**
+```json
+{
+  "rows": [
+    {
+      "id": "uuid",
+      "title": "Version 1.0",
+      "description": "Initial release",
+      "from_environment": "stage",
+      "to_environment": "production",
+      "status": "success",
+      "pages_copied": 10,
+      "audios_copied": 3,
+      "started_at": "2026-03-30T12:00:00.000Z",
+      "finished_at": "2026-03-30T12:00:05.000Z",
+      "project": { "id": "uuid", "name": "My Tour" },
+      "user": { "id": "uuid", "firstName": "John" }
+    }
+  ],
+  "count": 5
+}
+```
+
+---
+
+## 22. PWA Caches
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/pwa_caches` | Create PWA cache record |
+| GET | `/api/pwa_caches` | List PWA caches |
+| GET | `/api/pwa_caches/:id` | Get PWA cache by ID |
+| PUT | `/api/pwa_caches/:id` | Update PWA cache |
+| DELETE | `/api/pwa_caches/:id` | Delete PWA cache |
+
+**Permissions**: `CREATE_PWA_CACHES`, `READ_PWA_CACHES`, etc.
+
+### POST /api/pwa_caches
+
+**Request:**
+```json
+{
+  "data": {
+    "project": "project-uuid",
+    "cache_version": "v1.0.0",
+    "manifest_json": {
+      "name": "My Tour",
+      "short_name": "Tour"
+    },
+    "asset_list_json": [
+      "assets/image1.jpg",
+      "assets/image2.jpg"
+    ]
+  }
+}
+```
+
+---
+
+## 23. Presigned URL Requests
+
+### Standard CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/presigned_url_requests` | Create presign request |
+| GET | `/api/presigned_url_requests` | List presign requests |
+| GET | `/api/presigned_url_requests/:id` | Get presign request |
+| PUT | `/api/presigned_url_requests/:id` | Update presign request |
+| DELETE | `/api/presigned_url_requests/:id` | Delete presign request |
+
+**Permissions**: `CREATE_PRESIGNED_URL_REQUESTS`, `READ_PRESIGNED_URL_REQUESTS`, etc.
+
+### POST /api/presigned_url_requests
+
+**Request:**
+```json
+{
+  "data": {
+    "requested_key": "assets/new-upload.jpg",
+    "mime_type": "image/jpeg",
+    "requested_size_mb": 2.5,
+    "status": "pending",
+    "project": "project-uuid",
+    "user": "user-uuid"
+  }
+}
+```
+
+---
+
+## Error Codes Reference
+
+| Code | Message | Description |
+|------|---------|-------------|
+| 400 | Bad Request | Invalid input data or validation error |
+| 401 | Unauthorized | Missing or invalid JWT token |
+| 403 | Forbidden | Insufficient permissions |
+| 404 | Not Found | Resource does not exist |
+| 409 | Conflict | Resource conflict (e.g., duplicate) |
+| 422 | Unprocessable Entity | Validation failed |
+| 429 | Too Many Requests | Rate limit exceeded |
+| 500 | Internal Server Error | Unexpected server error |
+
+---
+
+## Headers Reference
+
+### Request Headers
+
+| Header | Description | Required |
+|--------|-------------|----------|
+| `Authorization` | `Bearer <token>` | For protected endpoints |
+| `Content-Type` | `application/json` | For JSON bodies |
+| `X-Runtime-Environment` | `dev`, `stage`, or `production` | For runtime context |
+| `X-Request-Id` | UUID for request tracing | Optional |
+
+### Response Headers
+
+| Header | Description |
+|--------|-------------|
+| `X-Request-Id` | Request ID for tracing |
+| `X-RateLimit-Limit` | Rate limit maximum |
+| `X-RateLimit-Remaining` | Remaining requests |
+| `X-RateLimit-Reset` | Reset timestamp |
+| `Retry-After` | Seconds until rate limit resets (on 429) |
+| `Cross-Origin-Resource-Policy` | `cross-origin` (on file downloads) |
diff --git a/backend/docs/backend-architecture.md b/backend/docs/backend-architecture.md
new file mode 100644
index 0000000..f841882
--- /dev/null
+++ b/backend/docs/backend-architecture.md
@@ -0,0 +1,681 @@
+# Backend Architecture Documentation
+
+This document provides a comprehensive analysis of the Tour Builder Platform backend architecture, including design patterns, layers, and implementation details.
+
+## Overview
+
+- **Runtime**: Node.js 24 LTS
+- **Framework**: Express.js 4.x
+- **ORM**: Sequelize 6.x with PostgreSQL
+- **Authentication**: Passport.js (JWT, Google OAuth, Microsoft OAuth)
+- **Documentation**: Swagger/OpenAPI 3.0
+- **Logging**: Pino (structured JSON logging)
+- **TypeScript/ESM**: the backend package is `"type": "module"` and active
+  backend source is strict TypeScript ESM.
+- **File Storage**: AWS S3 / Local filesystem (Strategy Pattern, provider-based)
+
+---
+
+## Architecture Diagram
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                           Express Application                            │
+│                              (src/index.ts)                              │
+└──────────────────────────────────────────────────────────────────────────┘
+                                      │
+                    ┌─────────────────┼─────────────────┐
+                    ▼                 ▼                 ▼
+┌────────────────────────┐  ┌────────────────┐  ┌────────────────────────┐
+│      Middleware        │  │   Rate Limiter │  │   Request Logger       │
+│  • runtimeContext      │  │  • auth (10/15m)│  │  • Pino structured    │
+│  • runtimePublic       │  │  • api (100/1m) │  │  • Request ID tracking │
+│  • checkPermissions    │  │  • upload (10/m)│  │  • Duration metrics    │
+│  • passport JWT        │  │  • download(200)│  └────────────────────────┘
+└────────────────────────┘  │  • search (30/m)│
+                            │  • AI (20/1m)   │
+                            └────────────────┘
+                                      │
+┌──────────────────────────────────────────────────────────────────────────┐
+│                             Routes Layer                                 │
+│                            (src/routes/*.ts)                              │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │ Factory-generated routes: router.factory.js                        │  │
+│  │   • Standard CRUD: POST /, PUT /:id, DELETE /:id, GET /, GET /:id  │  │
+│  │   • Extra: GET /count, GET /autocomplete, POST /deleteByIds        │  │
+│  │   • CSV export: GET /?filetype=csv                                 │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │ Custom routes: auth, file, publish, search, sql, runtime          │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                            Service Layer                                 │
+│                          (src/services/*.js)                             │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │ Factory-generated services: service.factory.js                     │  │
+│  │   • Transaction-wrapped CRUD operations                            │  │
+│  │   • Delegates to DB API layer                                      │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │ Custom services:                                                   │  │
+│  │   • auth.js - Authentication logic (signin, signup, password)      │  │
+│  │   • publish.ts - Publishing workflow service (dev→stage→production)│  │
+│  │   • file.ts - File storage operations                              │  │
+│  │   • email/index.js - Email sending via Nodemailer/SES              │  │
+│  │   • search.ts - Full-text search route                              │  │
+│  │   • pwa_manifest.js - PWA offline manifest generation              │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                           Database API Layer                             │
+│                            (src/db/api/*.js)                             │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │ GenericDBApi (base.api.js) - Template Method Pattern               │  │
+│  │   • Configurable: MODEL, SEARCHABLE_FIELDS, RANGE_FIELDS, etc.     │  │
+│  │   • CRUD: create, update, remove, deleteByIds                      │  │
+│  │   • Query: findBy, findAll, findAllAutocomplete                    │  │
+│  │   • Data Transform: getFieldMapping(), JSON_FIELDS, FIELD_DEFAULTS │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │ Entity APIs extend GenericDBApi:                                   │  │
+│  │   UsersDBApi, ProjectsDBApi, AssetsDBApi, TourPagesDBApi, etc.     │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                            Sequelize Models                              │
+│                          (src/db/models/*.ts)                            │
+│  Entity models + file model, loaded dynamically via loader.ts           │
+└──────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                             PostgreSQL                                   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Directory Structure
+
+```
+backend/src/
+├── index.ts                 # Application entry point
+├── config.ts                # Environment configuration
+├── helpers.ts               # Utility functions (wrapAsync, JWT, UUID validation)
+├── types/                   # Reusable strict TypeScript contracts for migrated code
+│
+├── auth/
+│   └── auth.ts              # Passport strategies (JWT, Google, Microsoft)
+│
+├── middlewares/
+│   ├── check-permissions.ts # RBAC permission checking
+│   ├── runtime-context.ts   # Runtime environment context (dev/stage/production)
+│   ├── runtime-public.ts    # Public runtime access control & field sanitization
+│   ├── rateLimiter.ts       # Rate limiting (auth, API, upload, download)
+│   └── upload.ts            # File upload handling (multer)
+│
+├── routes/
+│   ├── auth.ts              # Authentication routes (custom)
+│   ├── file.ts              # File upload/download routes (custom)
+│   ├── publish.ts           # Publishing workflow routes (custom)
+│   ├── search.ts            # Full-text search routes (custom)
+│   ├── runtime-context.ts   # Runtime context detection (custom)
+│   └── [entity].ts          # Entity CRUD routes
+│
+├── services/
+│   ├── auth.ts              # Authentication service
+│   ├── publish.ts           # Publishing workflow (dev→stage→production)
+│   ├── file.ts              # Unified file storage service
+│   ├── search.ts            # Full-text search service
+│   ├── file/                # File storage providers (S3, Local)
+│   │   ├── index.ts         # Module exports & provider factory
+│   │   ├── BaseStorageProvider.ts    # Abstract base class
+│   │   ├── S3StorageProvider.ts      # AWS S3 implementation
+│   │   ├── LocalStorageProvider.ts   # Local filesystem implementation
+│   │   └── UploadSessionManager.ts   # Chunked upload session management
+│   ├── email/
+│   │   ├── index.ts         # Email sender (Nodemailer/SES)
+│   │   └── list/            # Email templates
+│   ├── notifications/
+│   │   ├── helpers.ts       # Notification helpers
+│   │   └── errors/          # Error classes (ValidationError, ForbiddenError)
+│   └── [entity].ts          # Entity services
+│
+├── factories/
+│   ├── router.factory.ts    # Route generator (createEntityRouter)
+│   └── service.factory.ts   # Service generator (createEntityService)
+│
+├── db/
+│   ├── db-config.ts         # Database configuration (env-based)
+│   ├── umzug.ts             # Migration and seeder runner
+│   ├── models/
+│   │   ├── index.ts         # Model registry entrypoint
+│   │   ├── loader.ts        # Model loader
+│   │   └── [entity].ts      # Sequelize models
+│   ├── api/
+│   │   ├── base.api.ts      # GenericDBApi base class
+│   │   ├── runtime-context.ts # Runtime filtering helpers
+│   │   └── [entity].ts      # Entity DB APIs
+│   ├── migrations/          # Applied migration history
+│   └── seeders/             # Typed seed data files
+│
+└── utils/
+    ├── index.ts             # Utils barrel export
+    ├── errors.ts            # Error classes (AppError, NotFoundError, etc.)
+    ├── logger.ts            # Pino logger configuration
+    └── env-validation.ts    # Environment variable validation
+```
+
+---
+
+## Design Patterns
+
+### 1. Factory Pattern
+
+**Router Factory** (`factories/router.factory.js`)
+
+Generates standardized CRUD routes for entities:
+
+```javascript
+const { createEntityRouter } = require('../factories/router.factory');
+
+// Creates routes: POST /, PUT /:id, DELETE /:id, GET /, GET /:id, GET /count, GET /autocomplete
+module.exports = createEntityRouter('assets', AssetsService, AssetsDBApi, {
+  permissionEntity: 'assets',
+  csvFields: ['id', 'name', 'asset_type', 'createdAt'],
+});
+```
+
+**Service Factory** (`factories/service.factory.js`)
+
+Generates transaction-wrapped service classes:
+
+```javascript
+const { createEntityService } = require('../factories/service.factory');
+
+// Creates: create(), update(), remove(), deleteByIds(), bulkImport()
+module.exports = createEntityService(AssetsDBApi, { entityName: 'Asset' });
+```
+
+### 2. Template Method Pattern
+
+**GenericDBApi** (`db/api/base.api.js`)
+
+Base class with configurable hooks for entity-specific behavior:
+
+```javascript
+class AssetsDBApi extends GenericDBApi {
+  // Required: Define the Sequelize model
+  static get MODEL() { return db.assets; }
+
+  // Configurable behavior via static getters
+  static get SEARCHABLE_FIELDS() { return ['name', 'cdn_url']; }
+  static get RANGE_FIELDS() { return ['size_mb', 'width_px']; }
+  static get ENUM_FIELDS() { return ['asset_type', 'is_public']; }
+  static get JSON_FIELDS() { return ['settings_json']; }
+  static get FIELD_DEFAULTS() { return { type: { default: 'general' } }; }
+  static get ASSOCIATIONS() { return [{ field: 'project', setter: 'setProject' }]; }
+  static get FIND_BY_INCLUDES() { return [{ association: 'project' }]; }
+  static get FIND_ALL_INCLUDES() { return [{ model: db.projects, as: 'project' }]; }
+
+  // Custom field transformation
+  static getFieldMapping(data) {
+    return {
+      name: data.name || null,
+      asset_type: data.asset_type || null,
+      type: data.type || 'general',
+      // ...
+    };
+  }
+}
+```
+
+### 3. Strategy Pattern
+
+**File Storage Providers** (`services/file/`)
+
+Two concrete implementations with pluggable architecture:
+
+```
+BaseStorageProvider (abstract)
+    │
+    ├── S3StorageProvider       # AWS S3 implementation (with timeout/retry)
+    └── LocalStorageProvider    # Local filesystem implementation
+```
+
+The storage provider base, S3 provider, and local provider are migrated TS/ESM modules. The S3 implementation uses official AWS SDK v3 types; shared provider-domain contracts are in `src/types/file.ts`.
+
+Interface:
+- `upload(key, data, options)` → `{ key, url }`
+- `download(key)` → `{ body, contentType }`
+- `delete(key)` → `void`
+- `deleteMany(keys)` → `void`
+- `exists(key)` → `boolean`
+- `list(prefix)` → `string[]`
+- `getSignedUrl(key, expiresIn)` → `string`
+
+### 4. Middleware Chain Pattern
+
+Request flow through middleware stack:
+
+```
+Request → requestLogger → runtimeContextMiddleware → rateLimiter
+        → passport.authenticate('jwt') → checkCrudPermissions
+        → Route Handler → Service → DB API → Database
+        → Response
+```
+
+---
+
+## Layers in Detail
+
+### Entry Point (`src/index.ts`)
+
+Application bootstrap:
+
+1. **Security**: Helmet, CORS configuration
+2. **Logging**: Request logger middleware (Pino)
+3. **Authentication**: Passport JWT initialization
+4. **Rate Limiting**: Per-route rate limiters
+5. **Body Parsing**: JSON (1mb limit), applied after file routes
+6. **Runtime Context**: Environment detection middleware
+7. **Route Mounting**: Entity routes with auth/permissions
+8. **Error Handling**: Generic error handler
+9. **Static Files**: Public directory serving
+
+```javascript
+// Key route mounting patterns
+app.use('/api/auth', authRoutes);  // No JWT required
+app.use('/api/users', jwtAuth, usersRoutes);  // JWT required
+
+// Runtime public routes (production content accessible without auth)
+const mountRuntimeEntityRoute = (path, entityName, router) => {
+  app.use(path,
+    requireRuntimeReadOrAuth,           // JWT or public production
+    blockNonPublicRuntimeListEndpoints, // Block non-list endpoints
+    sanitizePublicRuntimeListResponse(entityName), // Filter sensitive fields
+    router
+  );
+};
+mountRuntimeEntityRoute('/api/projects', 'projects', projectsRoutes);
+mountRuntimeEntityRoute('/api/tour_pages', 'tour_pages', tour_pagesRoutes);
+```
+
+### Routes Layer
+
+**Factory-Generated Routes** provide standard CRUD:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/` | Create record |
+| POST | `/bulk-import` | Bulk import from CSV |
+| PUT | `/:id` | Update record |
+| DELETE | `/:id` | Delete record |
+| POST | `/deleteByIds` | Bulk delete |
+| GET | `/` | List with pagination & filters |
+| GET | `/count` | Count only |
+| GET | `/autocomplete` | Autocomplete search |
+| GET | `/:id` | Get single record |
+
+**Custom Routes** (auth, file, publish, search, runtime-context):
+
+| Route | Endpoints |
+|-------|-----------|
+| `/api/auth` | signin, signup, me, password-reset, verify-email, Google/Microsoft OAuth |
+| `/api/file` | upload, download, presign, upload-sessions (chunked) |
+| `/api/publish` | publish (stage→production), save-to-stage (dev→stage) |
+| `/api/search` | Global full-text search |
+| `/api/runtime-context` | Runtime environment detection |
+
+### Service Layer
+
+**Transaction Management**: Services wrap operations in transactions:
+
+```javascript
+static async create({ data, currentUser, transaction: externalTransaction, runtimeContext }) {
+  const transaction = externalTransaction || await db.sequelize.transaction();
+  const ownsTransaction = !externalTransaction;
+  try {
+    const record = await DBApi.create({ data, currentUser, transaction, runtimeContext });
+    if (ownsTransaction) await transaction.commit();
+    return record;
+  } catch (error) {
+    if (ownsTransaction) await transaction.rollback();
+    throw error;
+  }
+}
+```
+
+**Publish Service** (`services/publish.ts`):
+
+Implements the dev→stage→production workflow with:
+- Transaction locking to prevent concurrent publishes
+- Source key tracking for content lineage
+- Bulk copy operations for pages and audio tracks
+
+### Database API Layer
+
+**Query Building** in `findAll()`:
+
+| Filter Type | Example | SQL |
+|-------------|---------|-----|
+| Text search | `?name=foo` | `name ILIKE '%foo%'` |
+| Range | `?size_mbRange=[0,100]` | `size_mb >= 0 AND size_mb <= 100` |
+| Enum | `?asset_type=image` | `asset_type = 'image'` |
+| Relation | `?project=uuid` | JOIN with projects table |
+| Sort | `?field=name&sort=asc` | `ORDER BY name ASC` |
+| Pagination | `?page=1&limit=10` | `OFFSET 0 LIMIT 10` |
+
+---
+
+## Authentication & Authorization
+
+### Authentication Flow
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  POST /signin   │     │  Passport JWT   │     │   Protected     │
+│  → JWT Token    │────▶│  Middleware     │────▶│   Route         │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+                               │
+                               ▼
+                        req.currentUser = {
+                          id, email, app_role,
+                          custom_permissions
+                        }
+```
+
+### Authorization (RBAC)
+
+**Permission Check Flow** (`middlewares/check-permissions.ts`):
+
+1. Self-access bypass (user accessing own resource)
+2. Check custom permissions (user-specific)
+3. Check role permissions (from app_role)
+4. Fallback to Public role for unauthenticated
+
+**Permission Naming Convention**:
+- `CREATE_<ENTITY>` - Create records
+- `READ_<ENTITY>` - Read records
+- `UPDATE_<ENTITY>` - Modify records
+- `DELETE_<ENTITY>` - Delete records
+
+```javascript
+// Auto-generated from HTTP method
+const permissionName = `${METHOD_MAP[req.method]}_${name.toUpperCase()}`;
+// POST /api/assets → CREATE_ASSETS
+// GET /api/assets → READ_ASSETS
+```
+
+### Runtime Public Access
+
+For production content accessible without authentication:
+
+```javascript
+const requireRuntimeReadOrAuth = (req, res, next) => {
+  const isPublicEnvironment = req.runtimeContext?.headerEnvironment === 'production';
+  const isReadOnlyRequest = ['GET', 'OPTIONS'].includes(req.method);
+
+  if (isPublicEnvironment && isReadOnlyRequest && !hasAuthHeader) {
+    req.isRuntimePublicRequest = true;
+    return next();  // Allow without JWT
+  }
+
+  return jwtAuth(req, res, next);  // Require JWT
+};
+```
+
+---
+
+## Rate Limiting
+
+Pre-configured limiters (`middlewares/rateLimiter.ts`):
+
+| Limiter | Window | Max Requests | Use Case |
+|---------|--------|--------------|----------|
+| `authLimiter` | 15 min | 10 | Authentication endpoints |
+| `passwordResetLimiter` | 1 hour | 5 | Password reset |
+| `apiLimiter` | 1 min | 100 | General API |
+| `uploadLimiter` | 1 min | 10 | File uploads |
+| `downloadLimiter` | 1 min | 200 | File downloads |
+| `searchLimiter` | 1 min | 30 | Search queries |
+
+Headers returned:
+- `X-RateLimit-Limit`: Maximum requests
+- `X-RateLimit-Remaining`: Remaining requests
+- `X-RateLimit-Reset`: Reset time (ISO timestamp)
+- `Retry-After`: Seconds until reset (when limited)
+
+---
+
+## File Storage
+
+**Storage Provider Selection**:
+
+```javascript
+const provider = config.fileStorage.provider ||
+  (hasS3Credentials ? 's3' : hasGCloudCredentials ? 'gcloud' : 'local');
+```
+
+**S3 Operations**:
+
+| Operation | Method | Description |
+|-----------|--------|-------------|
+| Upload | `upload(key, data, options)` | Put object with metadata |
+| Download | `download(key)` | Get object stream |
+| Presign | `getSignedUrl(key, expiresIn)` | Generate presigned URL |
+| Delete | `delete(key)` / `deleteMany(keys)` | Remove objects |
+| Check | `exists(key)` | Head object |
+| List | `list(prefix)` | List objects with prefix |
+
+**Chunked Uploads** (`UploadSessionManager`):
+
+For large files, supports multipart upload sessions:
+1. `POST /upload-sessions/init` - Create session
+2. `POST /upload-sessions/:id/chunk` - Upload chunk
+3. `POST /upload-sessions/:id/finalize` - Complete upload
+
+---
+
+## Error Handling
+
+**Error Classes** (`utils/errors.js`):
+
+```javascript
+class AppError extends Error {
+  constructor(message, statusCode = 500, details = null) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.isOperational = true;
+  }
+}
+
+class NotFoundError extends AppError { statusCode = 404 }
+class ValidationError extends AppError { statusCode = 400 }
+class ForbiddenError extends AppError { statusCode = 403 }
+class UnauthorizedError extends AppError { statusCode = 401 }
+class ConflictError extends AppError { statusCode = 409 }
+```
+
+**Async Handler** (`helpers.ts`):
+
+```javascript
+// Wraps async route handlers to catch errors
+static wrapAsync(fn) {
+  return function(req, res, next) {
+    fn(req, res, next).catch(next);
+  };
+}
+```
+
+**Common Error Handler** (`helpers.ts`):
+
+```javascript
+static commonErrorHandler(error, req, res, _next) {
+  const statusCode = error.code || error.status;
+
+  if ([400, 401, 403, 404, 409, 422].includes(statusCode)) {
+    return res.status(statusCode).send(error.message);
+  }
+
+  console.error(error);
+  return res.status(500).send('Internal server error');
+}
+```
+
+---
+
+## Logging
+
+**Pino Logger** (`utils/logger.js`):
+
+Logger initialization is a bootstrap exception: it may read `process.env`
+directly because importing `config.ts` would create an initialization cycle.
+
+```javascript
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport: isDevelopment
+    ? { target: 'pino-pretty', options: { colorize: true } }
+    : undefined,
+  base: {
+    service: 'tour-builder-api',
+    env: process.env.NODE_ENV || 'development',
+  },
+});
+```
+
+**Request Logging**:
+
+```javascript
+function requestLogger(req, res, next) {
+  const requestId = req.headers['x-request-id'] || crypto.randomUUID();
+  req.log = logger.child({ requestId });
+  req.requestId = requestId;
+  res.setHeader('X-Request-Id', requestId);
+
+  res.on('finish', () => {
+    req.log.info({
+      method: req.method,
+      url: req.originalUrl,
+      status: res.statusCode,
+      duration: Date.now() - start,
+    }, 'Request completed');
+  });
+}
+```
+
+---
+
+## Configuration
+
+**Environment Variables** (`config.ts`):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECRET_KEY` | JWT signing key | UUID-based default |
+| `ADMIN_EMAIL` | Admin user email | `admin@flatlogic.com` |
+| `ADMIN_PASS` | Admin user password | Generated |
+| `AWS_S3_BUCKET` | S3 bucket name | - |
+| `AWS_S3_REGION` | S3 region | `us-east-1` |
+| `AWS_ACCESS_KEY_ID` | AWS access key | - |
+| `AWS_SECRET_ACCESS_KEY` | AWS secret key | - |
+| `GOOGLE_CLIENT_ID` | Google OAuth client ID | - |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret | - |
+| `MS_CLIENT_ID` | Microsoft OAuth client ID | - |
+| `MS_CLIENT_SECRET` | Microsoft OAuth client secret | - |
+| `EMAIL_USER` | SMTP username | - |
+| `EMAIL_PASS` | SMTP password | - |
+| `LOG_LEVEL` | Logging level | `info` |
+
+**Database Configuration** (`db/db-config.ts`):
+
+| Environment | Database | Logging |
+|-------------|----------|---------|
+| `production` | `DB_*` env vars | Disabled |
+| `development` | `db_tour_builder_platform` | Console |
+| `dev_stage` | `DB_*` env vars | Console |
+
+---
+
+## API Documentation
+
+Swagger/OpenAPI documentation is available at `/api-docs`.
+
+The served document is centralized in `backend/src/openapi/document.ts`. The
+OpenAPI module defines shared schemas, common parameters, reusable responses,
+and generated standard CRUD paths for every `createEntityRouter` resource. This
+keeps the documented factory contract aligned with the route factory endpoints:
+create, bulk import, update, delete, bulk delete, list, count, autocomplete,
+and get by ID.
+
+```javascript
+const specs = createOpenApiDocument({
+  serverUrl: config.server.swaggerServerUrl,
+});
+```
+
+When adding a new route, update `backend/src/openapi/document.ts` in the same
+change. For new factory-backed entities, add the entity schema and `CrudResource`
+entry; for custom routes, add an explicit path item.
+
+---
+
+## Health Check
+
+```javascript
+GET /api/health
+
+{
+  "status": "ok",           // or "degraded"
+  "timestamp": "2026-03-29T...",
+  "uptime": 12345.678,
+  "environment": "production",
+  "database": "connected"   // or "disconnected"
+}
+```
+
+---
+
+## Key Implementation Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Application entry, middleware setup, route mounting |
+| `src/config.ts` | Environment configuration |
+| `src/helpers.ts` | wrapAsync, commonErrorHandler, jwtSign, isUuidV4 |
+| `src/auth/auth.ts` | Passport strategies (JWT, Google, Microsoft) |
+| `src/factories/router.factory.ts` | Route generator for entities |
+| `src/factories/service.factory.ts` | Service generator for entities |
+| `src/db/api/base.api.ts` | GenericDBApi base class |
+| `src/middlewares/check-permissions.ts` | RBAC permission checking |
+| `src/middlewares/rateLimiter.ts` | Rate limiting configuration |
+| `src/middlewares/runtime-context.ts` | Runtime environment detection |
+| `src/middlewares/runtime-public.ts` | Public runtime access control & field sanitization |
+| `src/services/publish.ts` | Publishing workflow service |
+| `src/services/file/S3StorageProvider.ts` | S3 storage implementation using official AWS SDK v3 types |
+| `src/utils/logger.ts` | Pino logger configuration |
+| `src/utils/errors.ts` | Error class definitions |
+
+---
+
+## Best Practices Implemented
+
+1. **Factory Patterns** - Reduce boilerplate for CRUD operations
+2. **Template Method** - Configurable base class for DB operations
+3. **Strategy Pattern** - Pluggable storage providers
+4. **Middleware Chain** - Composable request processing
+5. **Transaction Management** - Consistent rollback on errors
+6. **Rate Limiting** - Protection against abuse
+7. **Structured Logging** - JSON logs with request IDs
+8. **Environment-Based Config** - Secure credential handling
+9. **Soft Deletes** - Paranoid models for data recovery
+10. **RBAC** - Fine-grained permission control
diff --git a/backend/docs/database-schema.md b/backend/docs/database-schema.md
new file mode 100644
index 0000000..a144a12
--- /dev/null
+++ b/backend/docs/database-schema.md
@@ -0,0 +1,1025 @@
+# Database Schema Documentation
+
+This document provides a comprehensive analysis of the Tour Builder Platform database schema, including all models, fields, relationships, constraints, and configurations.
+
+## Overview
+
+- **Database**: PostgreSQL
+- **ORM**: Sequelize v6
+- **Table Naming**: `freezeTableName: true` - table names match model names exactly
+- **Soft Delete**: All models use `paranoid: true` - records are soft-deleted via `deletedAt` timestamp
+- **Timestamps**: All models include `createdAt`, `updatedAt`, and `deletedAt` columns
+- **Primary Keys**: All models use UUID v4 as primary key
+
+## Database Configuration
+
+Configuration is environment-based in `backend/src/db/db-config.ts`:
+
+| Environment | Database | Logging |
+|-------------|----------|---------|
+| production | `DB_*` env vars | Disabled |
+| development | `db_tour_builder_platform` | Console |
+| dev_stage | `DB_*` env vars | Console |
+
+**Migration Settings:**
+- Migration storage: `sequelize` (SequelizeMeta table)
+- Seeder storage: `sequelize`
+
+---
+
+## Entity-Relationship Overview
+
+```
+┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
+│    users     │────<│project_memberships│>───│    projects     │
+└──────────────┘     └─────────────────┘     └──────────────────┘
+       │                                              │
+       │ app_roleId                                   │ hasMany
+       ▼                                              ▼
+┌──────────────┐                            ┌──────────────────┐
+│    roles     │                            │   tour_pages     │
+└──────────────┘                            │ (ui_schema_json) │
+       │                                    └──────────────────┘
+       │ belongsToMany
+       ▼
+┌──────────────┐
+│ permissions  │
+└──────────────┘
+
+┌──────────────┐
+│    assets    │────< asset_variants
+└──────────────┘
+
+┌────────────────────────┐     snapshotted from     ┌────────────────────────┐
+│ project_element_defaults│ ─────────────────────── │ element_type_defaults  │
+└────────────────────────┘      (source_element_id) └────────────────────────┘
+         │                                                   │
+         │ belongsTo                                         │ (global defaults)
+         ▼                                                   │
+┌──────────────────┐                                         │
+│    projects      │<────────────────────────────────────────┘
+└──────────────────┘    (templates for new projects)
+```
+
+**Note:** Page elements, navigation links, and transition videos are stored directly in `tour_pages.ui_schema_json` rather than in separate tables. This simplifies the data model and avoids ID remapping issues when publishing between environments.
+
+---
+
+## Core Models
+
+### 1. users
+
+User accounts for authentication and authorization.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `firstName` | TEXT | nullable | User's first name |
+| `lastName` | TEXT | nullable | User's last name |
+| `phoneNumber` | TEXT | nullable | Contact phone |
+| `email` | TEXT | NOT NULL, UNIQUE | Email (validated) |
+| `disabled` | BOOLEAN | NOT NULL, default: false | Account disabled flag |
+| `password` | TEXT | NOT NULL | Bcrypt hashed password |
+| `emailVerified` | BOOLEAN | NOT NULL, default: false | Email verification status |
+| `emailVerificationToken` | TEXT | nullable | Token for email verification |
+| `emailVerificationTokenExpiresAt` | DATE | nullable | Token expiry |
+| `passwordResetToken` | TEXT | nullable | Password reset token |
+| `passwordResetTokenExpiresAt` | DATE | nullable | Reset token expiry |
+| `provider` | TEXT | NOT NULL, default: 'local' | Auth provider (local, google, microsoft) |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication key |
+| `app_roleId` | UUID | FK → roles.id | User's application role |
+| `createdById` | UUID | FK → users.id | Record creator |
+| `updatedById` | UUID | FK → users.id | Last modifier |
+
+**Indexes:**
+- `email` (unique)
+- `app_roleId`
+- `deletedAt`
+
+**Associations:**
+- `belongsTo` roles (as `app_role`)
+- `hasMany` project_memberships
+- `hasMany` presigned_url_requests
+- `hasMany` publish_events
+- `hasMany` access_logs
+- `belongsToMany` permissions (as `custom_permissions`)
+- `hasMany` file (as `avatar`, polymorphic)
+
+**Hooks:**
+- `beforeCreate`: Trims string fields, auto-generates password for OAuth users, sets `emailVerified: true` for OAuth
+- `beforeUpdate`: Trims string fields
+
+---
+
+### 2. roles
+
+Application-level roles for RBAC.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `name` | TEXT | NOT NULL, len: 1-100 | Role name |
+| `role_customization` | TEXT | nullable | Custom role settings |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Associations:**
+- `hasMany` users (as `users_app_role`)
+- `belongsToMany` permissions (through `rolesPermissionsPermissions`)
+
+**Seeded Roles:**
+- Administrator (full access)
+- Platform Owner
+- Account Manager
+- Tour Designer
+- Content Reviewer
+- Analytics Viewer
+- Public (minimal access)
+
+---
+
+### 3. permissions
+
+Individual permission definitions for RBAC.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `name` | TEXT | NOT NULL, UNIQUE, len: 1-100 | Permission name |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Permission Naming Convention:**
+- `CREATE_<ENTITY>` - Create records
+- `READ_<ENTITY>` - Read records
+- `UPDATE_<ENTITY>` - Modify records
+- `DELETE_<ENTITY>` - Delete records
+- `READ_API_DOCS` - Access API documentation
+- `CREATE_SEARCH` - Perform searches
+
+**Seeded Entities with CRUD Permissions:**
+users, roles, permissions, projects, project_memberships, assets, asset_variants, presigned_url_requests, tour_pages, project_audio_tracks, publish_events, pwa_caches, access_logs, element_type_defaults, project_element_defaults
+
+Private production presentation access is intentionally not part of the generic
+CRUD permission seed set. It is represented by project visibility plus explicit
+customer grants in `production_presentation_access`.
+
+---
+
+### 4. projects
+
+Virtual tour projects - the main organizational unit.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `name` | TEXT | NOT NULL, len: 1-255 | Project name |
+| `slug` | TEXT | NOT NULL, UNIQUE, regex: `^[a-z0-9_-]+$/i`, len: 1-255 | URL-safe identifier |
+| `description` | TEXT | nullable | Project description |
+| `logo_url` | TEXT | nullable | Project logo URL |
+| `favicon_url` | TEXT | nullable | Favicon URL |
+| `og_image_url` | TEXT | nullable | Open Graph image URL |
+| `production_presentation_visibility` | ENUM | NOT NULL, default: 'public' | Production runtime visibility: `public`, `private` |
+| `design_width` | INTEGER | nullable, default: 1920 | Design canvas width (px) |
+| `design_height` | INTEGER | nullable, default: 1080 | Design canvas height (px) |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Indexes:**
+- `slug` (unique)
+- `deletedAt`
+
+**Associations:**
+- `hasMany` project_memberships
+- `hasMany` assets
+- `hasMany` presigned_url_requests
+- `hasMany` tour_pages
+- `hasMany` project_audio_tracks
+- `hasMany` project_element_defaults
+- `hasMany` publish_events
+- `hasMany` pwa_caches
+- `hasMany` access_logs
+- `hasMany` production_presentation_access
+- `hasMany` project_ui_control_settings
+
+**Cascade Behavior:** All child records are deleted when project is deleted.
+
+**Auto-Snapshot on Create:** When a project is created, all `element_type_defaults` records are automatically snapshotted to `project_element_defaults` for the new project.
+
+### Global UI Controls
+
+Global UI controls configure the system-owned fullscreen, sound, and offline
+buttons. Defaults live in `global_ui_control_defaults`, project/environment
+overrides live in `project_ui_control_settings`, and page overrides live in
+`tour_pages.global_ui_controls_settings_json`.
+
+Sizes are stored as canvas-width-relative percentage fields
+(`buttonSizePercent`, `iconSizePercent`, `borderRadiusPercent`). Positions are
+stored as canvas-relative percentages (`xPercent`, `yPercent`) for stable
+placement across devices.
+
+Icons, background colors, and border colors are state-specific:
+`defaultIconUrl`/`activeIconUrl`, `defaultBackgroundColor`/`activeBackgroundColor`,
+and `defaultBorderColor`/`activeBorderColor`.
+
+#### `global_ui_control_defaults`
+
+Singleton table for platform-wide defaults.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default UUIDv4 | Primary identifier |
+| `settings_json` | JSON | NOT NULL | Defaults for `offline`, `fullscreen`, `sound` |
+| `createdById` | UUID | nullable FK users | Creator |
+| `updatedById` | UUID | nullable FK users | Last updater |
+| `createdAt`, `updatedAt`, `deletedAt` | DATE | paranoid timestamps | Lifecycle fields |
+
+#### `project_ui_control_settings`
+
+Project/environment-level overrides.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default UUIDv4 | Primary identifier |
+| `projectId` | UUID | NOT NULL, FK projects, cascade delete | Owning project |
+| `environment` | ENUM | NOT NULL: `dev`, `stage`, `production` | Content environment |
+| `source_key` | TEXT | nullable | Snapshot/publish/clone provenance |
+| `settings_json` | JSON | NOT NULL | Project-level UI-control overrides |
+| `importHash` | STRING(255) | nullable unique | Import deduplication |
+| `createdById`, `updatedById` | UUID | nullable FK users | Audit users |
+| `createdAt`, `updatedAt`, `deletedAt` | DATE | paranoid timestamps | Lifecycle fields |
+
+**Indexes:**
+- unique partial index on `("projectId", environment)` where `deletedAt IS NULL`
+- index on `deletedAt`
+
+---
+
+### 5. production_presentation_access
+
+Explicit customer access grants for private production presentations.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `projectId` | UUID | FK → projects.id, NOT NULL | Private production presentation project |
+| `userId` | UUID | FK → users.id, NOT NULL | Customer user allowed to view the presentation |
+| `createdById` | UUID | FK → users.id | Record creator |
+| `updatedById` | UUID | FK → users.id | Last modifier |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Indexes:**
+- `projectId`
+- `userId`
+- `projectId, userId` (unique for active rows where `deletedAt IS NULL`)
+
+**Access Rules:**
+- Public production projects do not require rows in this table.
+- Staff users with any RBAC permission can view every private production presentation.
+- Public-role customer users with no RBAC permissions need an active row for each private production presentation.
+
+---
+
+### 6. project_memberships
+
+Junction table linking users to projects with access levels.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `access_level` | ENUM | NOT NULL, default: 'viewer' | Access level: `owner`, `editor`, `reviewer`, `viewer` |
+| `is_active` | BOOLEAN | NOT NULL, default: false | Membership active status |
+| `invited_at` | DATE | nullable | Invitation timestamp |
+| `accepted_at` | DATE | nullable | Acceptance timestamp |
+| `projectId` | UUID | FK → projects.id | Associated project |
+| `userId` | UUID | FK → users.id | Associated user |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Indexes:**
+- `projectId`
+- `userId`
+- `projectId, userId` (unique composite)
+- `is_active`
+- `deletedAt`
+
+**Cascade Behavior:** Deleted when associated project or user is deleted.
+
+---
+
+## Tour Content Models
+
+### 7. tour_pages
+
+Individual pages/scenes within a tour.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `environment` | ENUM | NOT NULL, default: 'dev' | Environment: `dev`, `stage`, `production` |
+| `source_key` | TEXT | nullable | Reference to source version when published |
+| `name` | TEXT | NOT NULL, len: 1-255 | Page display name |
+| `slug` | TEXT | NOT NULL, regex: `^[a-z0-9_-]+$/i`, len: 1-255 | URL-safe identifier |
+| `sort_order` | INTEGER | NOT NULL, default: 0 | Presentation display order; first sorted page is the entry page |
+| `background_image_url` | TEXT | nullable | Background image URL |
+| `background_video_url` | TEXT | nullable | Background video URL |
+| `background_embed_url` | TEXT | nullable | Background 360/embed URL |
+| `background_audio_url` | TEXT | nullable | Background audio URL |
+| `background_loop` | BOOLEAN | NOT NULL, default: false | Loop background media |
+| `background_video_autoplay` | BOOLEAN | NOT NULL, default: true | Autoplay background video |
+| `background_video_loop` | BOOLEAN | NOT NULL, default: true | Loop background video |
+| `background_video_muted` | BOOLEAN | NOT NULL, default: true | Mute background video |
+| `background_video_start_time` | DECIMAL(10,1) | nullable | Background video start time (seconds) |
+| `background_video_end_time` | DECIMAL(10,1) | nullable | Background video end time (seconds) |
+| `background_video_play_once` | BOOLEAN | NOT NULL, default: false | Play video only once per session (show last frame on revisit) |
+| `background_audio_autoplay` | BOOLEAN | NOT NULL, default: true | Autoplay background audio |
+| `background_audio_loop` | BOOLEAN | NOT NULL, default: true | Loop background audio |
+| `background_audio_start_time` | DECIMAL(10,1) | nullable | Background audio start time (seconds) |
+| `background_audio_end_time` | DECIMAL(10,1) | nullable | Background audio end time (seconds) |
+| `design_width` | INTEGER | nullable, default: null | Design canvas width (px) - copied from project on save |
+| `design_height` | INTEGER | nullable, default: null | Design canvas height (px) - copied from project on save |
+| `requires_auth` | BOOLEAN | NOT NULL, default: false | Requires authentication |
+| `ui_schema_json` | JSON | nullable | UI element schema |
+| `projectId` | UUID | FK → projects.id | Parent project |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Indexes:**
+- `projectId`
+- `projectId, environment, slug` (unique composite)
+- `projectId, environment, sort_order`
+- `deletedAt`
+
+**Ordering semantics:**
+- Constructor page reordering updates `sort_order` for dev pages only.
+- Constructor page duplication creates a new dev row with a
+  unique slug, fresh page ID, fresh inline element IDs in `ui_schema_json`, and
+  `sort_order = max(project dev sort_order) + 1`.
+- Constructor page deletion removes the dev row through the standard
+  `DELETE /api/tour_pages/:id` endpoint; stage and production keep their
+  previous copies until Save to Stage and Publish run.
+- Runtime loaders sort by `sort_order`; the first page after sorting is the
+  presentation entry page.
+- Save to Stage copies dev `sort_order` to stage. Publish copies stage
+  `sort_order` to production.
+
+**Associations:**
+- `belongsTo` projects (as `project`)
+
+**UI Schema JSON Structure:**
+The `ui_schema_json` field contains all page elements and navigation configuration:
+```json
+{
+  "elements": [{
+    "id": "unique-element-id",
+    "type": "navigation_next",
+    "name": "Next Page Button",
+    "xPercent": 90,
+    "yPercent": 85,
+    "widthPercent": 8,
+    "heightPercent": 10,
+    "targetPageSlug": "page-2",
+    "transitionVideoUrl": "assets/.../transition.mp4",
+    "iconUrl": "assets/.../icon.png",
+    "styleJson": { ... }
+  }]
+}
+```
+
+**Element Types:**
+- `navigation_next` - Forward navigation button
+- `navigation_prev` - Back navigation button
+- `spot` - Hotspot/clickable area
+- `description` - Text description
+- `tooltip` - Hover tooltip
+- `gallery` - Image gallery
+- `carousel` - Image carousel
+- `logo` - Logo element
+- `video_player` - Video player
+- `audio_player` - Audio player
+- `popup` - Popup/modal
+
+---
+
+## Asset Management Models
+
+### 7. assets
+
+Media files (images, videos, audio, documents) used in tours.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `name` | TEXT | nullable, len: 0-255 | Asset display name |
+| `asset_type` | ENUM | NOT NULL | Media type: `image`, `video`, `audio`, `file` |
+| `type` | ENUM | NOT NULL, default: 'general' | Usage type (see values below) |
+| `cdn_url` | TEXT | nullable | Public CDN URL |
+| `storage_key` | TEXT | nullable | S3/storage key |
+| `mime_type` | TEXT | nullable, validated | MIME type (e.g., `image/png`) |
+| `size_mb` | DECIMAL | nullable | File size in MB |
+| `width_px` | INTEGER | nullable | Width in pixels |
+| `height_px` | INTEGER | nullable | Height in pixels |
+| `duration_sec` | DECIMAL | nullable | Duration for audio/video |
+| `frame_rate` | DECIMAL | nullable | Video FPS from backend ffprobe |
+| `checksum` | TEXT | nullable | File checksum |
+| `is_public` | BOOLEAN | NOT NULL, default: false | Publicly accessible |
+| `projectId` | UUID | FK → projects.id | Parent project |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Asset Usage Types:**
+- `icon` - UI icons
+- `background_image` - Page backgrounds
+- `audio` - Audio files
+- `video` - Video files
+- `transition` - Transition videos
+- `logo` - Project logos
+- `favicon` - Favicon images
+- `document` - PDF/documents
+- `general` - General assets
+
+**Indexes:**
+- `projectId`
+- `storage_key` partial active-row index (`assets_storage_key_active`, where `deletedAt IS NULL` and `storage_key IS NOT NULL`) for transition/reversed-video lookup by canonical storage key
+- `asset_type`
+- `type`
+- `is_public`
+- `deletedAt`
+
+**Associations:**
+- `belongsTo` projects (as `project`)
+- `hasMany` asset_variants (as `asset_variants_asset`)
+
+---
+
+### 8. asset_variants
+
+Processed variants of assets (thumbnails, transcoded videos, reversed videos, etc.).
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `variant_type` | ENUM | nullable | Variant type (see values below) |
+| `cdn_url` | TEXT | nullable, len: 0-2048, URL validated | Variant CDN URL |
+| `storage_key` | TEXT | nullable | Private storage path (e.g., `assets/{assetId}/reversed.mp4`) |
+| `width_px` | INTEGER | nullable, min: 0 | Width in pixels |
+| `height_px` | INTEGER | nullable, min: 0 | Height in pixels |
+| `size_mb` | DECIMAL | nullable, min: 0 | File size in MB |
+| `assetId` | UUID | FK → assets.id | Parent asset |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Variant Types:**
+- `thumbnail` - Small preview
+- `preview` - Medium preview
+- `webp` - WebP format
+- `mp4_low` - Low-quality MP4
+- `mp4_high` - High-quality MP4
+- `original` - Original file
+- `reversed` - Reversed video for back navigation transitions (generated server-side with FFmpeg)
+
+**Cascade Behavior:** Deleted when parent asset is deleted.
+
+**Indexes:**
+- `assetId, variant_type` partial active-row index (`asset_variants_asset_id_variant_type_active`, where `deletedAt IS NULL`) for asset variant joins and reversed-variant lookup
+
+---
+
+### 9. presigned_url_requests
+
+Tracks presigned URL requests for secure uploads/downloads.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `purpose` | ENUM | nullable | Purpose: `upload`, `download` |
+| `asset_type` | ENUM | nullable | Asset type: `image`, `video`, `audio`, `file` |
+| `requested_key` | TEXT | nullable, len: 0-1024 | Requested storage key |
+| `mime_type` | TEXT | nullable, len: 0-255, validated | Expected MIME type |
+| `requested_size_mb` | DECIMAL | nullable, min: 0 | Expected file size |
+| `expires_at` | DATE | nullable | URL expiration time |
+| `status` | TEXT | nullable | Request status |
+| `projectId` | UUID | FK → projects.id | Associated project |
+| `userId` | UUID | FK → users.id | Requesting user |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+---
+
+## Audio & Media Models
+
+### 10. project_audio_tracks
+
+Background audio tracks for projects.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `environment` | ENUM | NOT NULL, default: 'dev' | Environment: `dev`, `stage`, `production` |
+| `source_key` | TEXT | nullable | Reference to source version when published |
+| `name` | TEXT | nullable, len: 0-255 | Track name |
+| `slug` | TEXT | nullable | URL-safe identifier |
+| `url` | TEXT | nullable | Audio file URL |
+| `loop` | BOOLEAN | NOT NULL, default: false | Loop playback |
+| `volume` | DECIMAL | nullable, min: 0, max: 1 | Volume level (0.0-1.0) |
+| `sort_order` | INTEGER | nullable | Playback order |
+| `is_enabled` | BOOLEAN | NOT NULL, default: false | Track enabled |
+| `projectId` | UUID | FK → projects.id | Parent project |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Note:** The `environment` field is NOT NULL with default 'dev' for consistency with `tour_pages`.
+
+---
+
+### 11. project_transition_settings
+
+Environment-aware project-level transition settings for CSS-based page transitions. Settings cascade: Element → Project → Global → Hardcoded defaults.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `environment` | ENUM | NOT NULL | Environment: `dev`, `stage`, `production` |
+| `source_key` | TEXT | nullable | Reference to source record when published |
+| `transition_type` | TEXT | NOT NULL, default: 'fade' | CSS transition type (`fade`, `none`) |
+| `duration_ms` | INTEGER | NOT NULL, default: 700 | Transition duration in milliseconds |
+| `easing` | TEXT | NOT NULL, default: 'ease-in-out' | CSS easing function |
+| `overlay_color` | TEXT | NOT NULL, default: '#000000' | Transition overlay color |
+| `projectId` | UUID | FK → projects.id, NOT NULL | Parent project |
+| `createdById` | UUID | FK → users.id, nullable | Creator user |
+| `updatedById` | UUID | FK → users.id, nullable | Last updater |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Indexes:**
+- `project_transition_settings_project_env_unique` - UNIQUE on (projectId, environment) WHERE deletedAt IS NULL
+
+**Associations:**
+- `belongsTo` projects (as `project`) - CASCADE on delete
+- `belongsTo` users (as `createdBy`, `updatedBy`)
+
+**Publishing Integration:** Copied between environments during Save to Stage (dev → stage) and Publish (stage → production). The `source_key` tracks lineage.
+
+**Cascade Resolution:** When determining transition settings:
+1. Element-level settings (from `ui_schema_json`)
+2. Project-level settings (this table, environment-specific)
+3. Global defaults (`global_transition_defaults`)
+4. Hardcoded fallback (fade, 700ms, ease-in-out, #000000)
+
+---
+
+## Publishing & Caching Models
+
+### 12. publish_events
+
+Records of content publishing between environments.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `title` | STRING | nullable, len: 0-255 | Event title |
+| `description` | TEXT | nullable, len: 0-5000 | Event description |
+| `from_environment` | ENUM | NOT NULL | Source: `dev`, `stage`, `production` |
+| `to_environment` | ENUM | NOT NULL | Target: `dev`, `stage`, `production` |
+| `started_at` | DATE | nullable | Start timestamp |
+| `finished_at` | DATE | nullable | Completion timestamp |
+| `status` | ENUM | NOT NULL, default: 'queued' | Status: `queued`, `running`, `success`, `failed` |
+| `error_message` | TEXT | nullable | Error details |
+| `pages_copied` | INTEGER | nullable, min: 0 | Pages copied count |
+| `audios_copied` | INTEGER | nullable, min: 0 | Audio tracks copied count |
+| `projectId` | UUID | FK → projects.id | Published project |
+| `userId` | UUID | FK → users.id | Publishing user |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Indexes:**
+- `projectId`
+- `userId`
+- `status`
+- `started_at`
+
+**Cascade Behavior:** `userId` set to NULL when user is deleted (preserves audit trail).
+
+---
+
+### 13. pwa_caches
+
+PWA cache configurations for offline support.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `environment` | ENUM | nullable | Environment: `dev`, `stage`, `production` |
+| `cache_version` | TEXT | nullable, len: 0-255 | Cache version string |
+| `manifest_json` | JSON | nullable | PWA manifest configuration |
+| `asset_list_json` | JSON | nullable | List of cached assets |
+| `generated_at` | DATE | nullable | Generation timestamp |
+| `is_active` | BOOLEAN | NOT NULL, default: false | Cache active status |
+| `projectId` | UUID | FK → projects.id | Parent project |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+---
+
+## Audit & Logging Models
+
+### 14. access_logs
+
+Audit trail for tour access.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `environment` | ENUM | NOT NULL | Access context: `admin`, `stage`, `production` |
+| `path` | TEXT | nullable, len: 0-2048 | Accessed path |
+| `ip_address` | TEXT | nullable, len: 0-45 | Client IP (IPv4/IPv6) |
+| `user_agent` | TEXT | nullable, len: 0-1024 | Browser user agent |
+| `accessed_at` | DATE | NOT NULL, default: NOW | Access timestamp |
+| `projectId` | UUID | FK → projects.id | Accessed project |
+| `userId` | UUID | FK → users.id | Accessing user (if authenticated) |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Indexes:**
+- `projectId`
+- `environment`
+- `userId`
+- `accessed_at`
+
+**Cascade Behavior:** `userId` set to NULL when user is deleted (preserves audit trail).
+
+---
+
+## Element Default Settings Models
+
+These models implement a two-tier settings hierarchy for UI elements:
+1. **Global defaults** (`element_type_defaults`) - Platform-wide default settings per element type
+2. **Project defaults** (`project_element_defaults`) - Project-specific overrides, snapshotted from global on project creation
+
+Instance element settings are stored directly in `tour_pages.ui_schema_json` as part of each element's configuration.
+
+### 15. element_type_defaults
+
+Global platform-wide default settings for each element type. These serve as templates that are snapshotted to new projects.
+
+**Note:** This table was renamed from `ui_elements` to `element_type_defaults` for clarity.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `element_type` | TEXT | NOT NULL, UNIQUE, len: 1-100 | Element type identifier |
+| `name` | TEXT | NOT NULL, len: 1-255 | Display name |
+| `sort_order` | INTEGER | NOT NULL, default: 0 | Display order in UI |
+| `is_active` | VIRTUAL | getter: true | Virtual active field |
+| `settings_json` | TEXT | nullable | Default settings JSON |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Field Aliasing:** The model exposes `default_settings_json` as a property name, but it maps to the `settings_json` column in the database via `field: 'settings_json'`. This provides a clearer API name while maintaining backward compatibility with the database schema.
+
+**Virtual Field:** `is_active` is a VIRTUAL field that always returns `true` (computed, not stored in database).
+
+**Indexes:**
+- `element_type` (unique)
+- `sort_order`
+- `deletedAt`
+
+**Associations:**
+- `hasMany` project_element_defaults (as `project_defaults`)
+
+**Auto-Initialization:** The API includes an `ensureInitialized()` method that automatically seeds default records if the table is empty. This runs before any CRUD operation.
+
+**Seeded Element Types (11 types auto-seeded):**
+- `navigation_next` - Forward navigation button (sort_order: 1)
+- `navigation_prev` - Back navigation button (sort_order: 2)
+- `tooltip` - Hover tooltip (sort_order: 3)
+- `description` - Text description (sort_order: 4)
+- `gallery` - Image gallery (sort_order: 5)
+- `carousel` - Image carousel (sort_order: 6)
+- `video_player` - Video player (sort_order: 7)
+- `audio_player` - Audio player (sort_order: 8)
+- `spot` - Hotspot/clickable area (sort_order: 9)
+- `logo` - Logo element (sort_order: 10)
+- `popup` - Popup/modal (sort_order: 11)
+
+---
+
+### 16. project_element_defaults
+
+Project-specific element default settings. Created automatically when a project is created by snapshotting all global `element_type_defaults`. Can be customized per-project without affecting global defaults or other projects.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `element_type` | TEXT | NOT NULL, len: 1-100 | Element type identifier |
+| `name` | TEXT | nullable, len: 0-255 | Custom display name |
+| `sort_order` | INTEGER | NOT NULL, default: 0 | Display order in UI |
+| `settings_json` | TEXT | nullable | Project-specific settings JSON |
+| `source_element_id` | UUID | FK → element_type_defaults.id, nullable | Reference to global default (for reset/diff) |
+| `snapshot_version` | INTEGER | NOT NULL, default: 1 | Version counter (incremented on reset) |
+| `projectId` | UUID | FK → projects.id, NOT NULL | Parent project |
+| `importHash` | STRING(255) | UNIQUE, nullable | Import deduplication |
+
+**Indexes:**
+- `projectId`
+- `projectId, element_type` (unique composite)
+- `element_type`
+- `source_element_id`
+- `deletedAt`
+
+**Associations:**
+- `belongsTo` projects (as `project`) - CASCADE on delete
+- `belongsTo` element_type_defaults (as `source_element`) - SET NULL on delete
+
+**Custom findAll with Project Filtering:**
+The API implements a custom `findAll()` method that supports filtering by project:
+- Query params: `?projectId=<uuid>` or `?project=<uuid|name>`
+- Supports multiple values: `?projectId=uuid1|uuid2`
+- Can filter by project UUID or project name (case-insensitive)
+- Includes related `project` and `source_element` associations
+- Default ordering: `sort_order ASC`
+
+**Auto-Snapshot Behavior:**
+When a new project is created, all records from `element_type_defaults` are automatically copied to `project_element_defaults` for that project. This ensures each project starts with consistent defaults while allowing customization.
+
+**Reset Functionality:**
+Projects can reset their element defaults back to the current global defaults via the `/api/project-element-defaults/:id/reset` endpoint. This increments `snapshot_version` and copies current global settings.
+
+**Diff Functionality:**
+The `/api/project-element-defaults/:id/diff` endpoint compares project defaults with global defaults to show customizations.
+
+---
+
+### 16. file (table: `files`)
+
+Polymorphic file attachments (e.g., user avatars).
+
+**Note:** This model does NOT have `freezeTableName: true`, so the table name is pluralized to `files`.
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `id` | UUID | PK, default: UUIDv4 | Primary identifier |
+| `belongsTo` | STRING(255) | nullable | Parent table name |
+| `belongsToId` | UUID | nullable | Parent record ID |
+| `belongsToColumn` | STRING(255) | nullable | Column name |
+| `name` | STRING(2083) | NOT NULL | File name |
+| `sizeInBytes` | INTEGER | nullable | File size |
+| `privateUrl` | STRING(2083) | nullable | Private storage URL |
+| `publicUrl` | STRING(2083) | NOT NULL | Public access URL |
+
+**Polymorphic Usage:**
+Files are attached to records via `belongsTo`/`belongsToId`/`belongsToColumn` columns.
+Example: User avatar has `belongsTo: 'users'`, `belongsToId: <user_id>`, `belongsToColumn: 'avatar'`
+
+---
+
+## Junction Tables
+
+### rolesPermissionsPermissions
+
+Many-to-many relationship between roles and permissions.
+
+| Field | Type | Constraints |
+|-------|------|-------------|
+| `roles_permissionsId` | UUID | PK, FK → roles.id |
+| `permissionId` | UUID | PK, FK → permissions.id |
+| `createdAt` | TIMESTAMP WITH TIME ZONE | NOT NULL |
+| `updatedAt` | TIMESTAMP WITH TIME ZONE | NOT NULL |
+
+**Indexes:**
+- `permissionId`
+
+### usersCustom_permissionsPermissions
+
+Many-to-many relationship for user custom permissions.
+
+| Field | Type | Constraints |
+|-------|------|-------------|
+| `users_custom_permissionsId` | UUID | FK → users.id |
+| `permissionId` | UUID | FK → permissions.id |
+
+---
+
+## Database Indexes Summary
+
+| Table | Index | Fields | Type |
+|-------|-------|--------|------|
+| users | email | email | unique |
+| users | app_roleId | app_roleId | - |
+| users | deletedAt | deletedAt | - |
+| projects | slug | slug | unique |
+| projects | deletedAt | deletedAt | - |
+| production_presentation_access | projectId | projectId | - |
+| production_presentation_access | userId | userId | - |
+| production_presentation_access | composite | projectId, userId | unique active rows |
+| project_memberships | composite | projectId, userId | unique |
+| tour_pages | composite | projectId, environment, slug | unique |
+| tour_pages | sort | projectId, environment, sort_order | - |
+| assets | projectId | projectId | - |
+| assets | asset_type | asset_type | - |
+| assets | type | type | - |
+| assets | is_public | is_public | - |
+| element_type_defaults | element_type | element_type | unique |
+| element_type_defaults | sort_order | sort_order | - |
+| element_type_defaults | deletedAt | deletedAt | - |
+| project_element_defaults | projectId | projectId | - |
+| project_element_defaults | composite | projectId, element_type | unique |
+| project_element_defaults | element_type | element_type | - |
+| project_element_defaults | source_element_id | source_element_id | - |
+| project_element_defaults | deletedAt | deletedAt | - |
+| publish_events | status | status | - |
+| publish_events | started_at | started_at | - |
+| access_logs | accessed_at | accessed_at | - |
+
+---
+
+## Foreign Key Constraints
+
+All foreign key constraints are enforced at the database level via migration `20260319000001-add-foreign-key-constraints.js`.
+
+| Child Table | Column | Parent Table | On Delete | On Update |
+|-------------|--------|--------------|-----------|-----------|
+| asset_variants | assetId | assets | CASCADE | CASCADE |
+| assets | projectId | projects | CASCADE | CASCADE |
+| tour_pages | projectId | projects | CASCADE | CASCADE |
+| project_memberships | projectId | projects | CASCADE | CASCADE |
+| project_memberships | userId | users | CASCADE | CASCADE |
+| production_presentation_access | projectId | projects | CASCADE | CASCADE |
+| production_presentation_access | userId | users | CASCADE | CASCADE |
+| production_presentation_access | createdById | users | SET NULL | CASCADE |
+| production_presentation_access | updatedById | users | SET NULL | CASCADE |
+| presigned_url_requests | projectId | projects | CASCADE | CASCADE |
+| presigned_url_requests | userId | users | CASCADE | CASCADE |
+| project_audio_tracks | projectId | projects | CASCADE | CASCADE |
+| project_element_defaults | projectId | projects | CASCADE | CASCADE |
+| project_element_defaults | source_element_id | element_type_defaults | SET NULL | CASCADE |
+| publish_events | projectId | projects | CASCADE | CASCADE |
+| publish_events | userId | users | SET NULL | CASCADE |
+| pwa_caches | projectId | projects | CASCADE | CASCADE |
+| access_logs | projectId | projects | CASCADE | CASCADE |
+| access_logs | userId | users | SET NULL | CASCADE |
+| users | app_roleId | roles | SET NULL | CASCADE |
+
+---
+
+## Migration History
+
+| Migration | Description |
+|-----------|-------------|
+| `20260319000001-add-foreign-key-constraints.js` | Adds all FK constraints to enforce referential integrity |
+| `20260319000002-remove-redundant-deletion-columns.js` | Removes deprecated `is_deleted` and `deleted_at_time` columns from assets and projects |
+| `20260326000001-rename-ui-elements-to-element-type-defaults.js` | Renames `ui_elements` table to `element_type_defaults` for clarity |
+| `20260326000002-convert-element-type-enum-to-text.js` | Converts element type from ENUM to TEXT for flexibility |
+| `20260326000003-create-project-element-defaults.js` | Creates `project_element_defaults` table for project-specific element settings |
+| `20260326000004-backfill-project-element-defaults.js` | Backfills `project_element_defaults` for existing projects by snapshotting global defaults |
+| `20260326000005-fix-project-audio-tracks-environment.js` | Fixes `project_audio_tracks.environment` to NOT NULL with default 'dev' |
+| `20260326000006-copy-dev-to-stage.js` | Copies existing dev content to stage environment for all projects (initializes dev→stage workflow) |
+| `20260326043002-enforce-environment-not-null.js` | Enforces NOT NULL constraint on environment columns in tour_pages and transitions |
+| `20260326050442-remove-project-phase-column.js` | Removes redundant `phase` column from projects table (environment is on tour_pages) |
+| `20260326054410-remove-entry-page-slug-column.js` | Removes `entry_page_slug` from projects (entry page is first by sort_order) |
+| `20260326060000-convert-targetpageid-to-slug.js` | Converts `targetPageId` to `targetPageSlug` in ui_schema_json for environment-safe navigation |
+| `20260326060001-drop-page-elements-table.js` | Drops unused `page_elements` table (data stored in ui_schema_json) |
+| `20260326060002-drop-page-links-table.js` | Drops unused `page_links` table (navigation stored in ui_schema_json) |
+| `20260326060003-drop-transitions-table.js` | Drops unused `transitions` table (transitionVideoUrl stored in ui_schema_json) |
+| `20260326171017-add-missing-element-type-defaults.js` | Adds missing element types (spot, logo, popup) to element_type_defaults and backfills project_element_defaults |
+| `20260327000001-sync-all-element-type-defaults.js` | Syncs all 11 element types with correct sort_order and backfills missing project_element_defaults for all projects |
+| `20260331024423-remove-unused-theme-columns-from-projects.js` | Removes unused `theme_config_json`, `custom_css_json`, `cdn_base_url` columns from projects table |
+| `20260331054340-remove-duplicate-element-type-defaults.js` | Removes duplicate element_type_defaults records created during earlier migrations |
+| `20260331063424-cleanup-invalid-element-type-defaults.js` | Cleans up invalid element_type_defaults entries and ensures data integrity |
+| `20260403000001-add-background-video-settings.js` | Adds background video playback settings to tour_pages (autoplay, loop, muted, start_time, end_time) |
+| `20260409000001-add-design-dimensions-to-projects.js` | Adds design_width and design_height columns to projects table for canvas scaling |
+| `20260409111309-add-design-dimensions-to-tour-pages.js` | Adds design_width and design_height columns to tour_pages table for presentation isolation |
+| `20260422000001-add-background-video-play-once.js` | Adds background_video_play_once column to tour_pages for session-scoped single playback |
+| `20260605000001-add-background-audio-settings.js` | Adds background audio playback settings to tour_pages (autoplay, loop, start_time, end_time) |
+| `20260613000001-add-background-embed-url-to-tour-pages.js` | Adds background_embed_url to tour_pages for 360/embed page backgrounds |
+| `20260626000001-add-private-production-presentation-access.js` | Adds project production visibility and customer access grants for private production presentations |
+| `20260626000002-grant-account-manager-create-users.js` | Grants `CREATE_USERS` to Account Manager for customer viewer creation |
+
+---
+
+## Seeders
+
+| Seeder | Description |
+|--------|-------------|
+| `20200430130759-admin-user.js` | Creates initial admin and test users |
+| `20200430130760-user-roles.js` | Creates roles, permissions, and role-permission assignments |
+| `20231127130745-sample-data.js` | Creates sample projects, pages, assets, and other demo data |
+
+**Initial Users:**
+- Admin: `admin@flatlogic.com` (admin password from config)
+- John Doe: `john@doe.com` (user password from config)
+- Client: `client@hello.com` (user password from config)
+
+---
+
+## Base DB API Patterns
+
+All entity DB APIs extend `GenericDBApi` which provides:
+
+### Configurable Properties
+- `MODEL` - Sequelize model reference (required, must be defined in subclass)
+- `TABLE_NAME` - Derived from MODEL.getTableName()
+- `SEARCHABLE_FIELDS` - Text search fields (ILIKE)
+- `RANGE_FIELDS` - Date/number range filters
+- `ENUM_FIELDS` - Exact match filters
+- `RELATION_FILTERS` - Related entity filters
+- `CSV_FIELDS` - Export field list (default: `['id', 'createdAt']`)
+- `AUTOCOMPLETE_FIELD` - Field for autocomplete (default: 'name')
+- `ASSOCIATIONS` - Many-to-many relationships
+- `FIND_BY_INCLUDES` - Eager loading for findBy
+- `FIND_ALL_INCLUDES` - Eager loading for findAll
+- `getFieldMapping(data)` - Transform input data before save (default: returns data unchanged)
+
+### Standard Methods
+- `create(data, options)` - Create record with associations
+- `bulkImport(data, options)` - Bulk create records
+- `update({ id, data, currentUser, transaction, runtimeContext })` - Update record
+- `deleteByIds({ ids, currentUser, transaction, runtimeContext })` - Soft delete multiple records
+- `remove({ id, currentUser, transaction, runtimeContext })` - Soft delete single record
+- `findBy(where, options)` - Find single record
+- `findAll(filter, options)` - Paginated list with filters
+- `findAllAutocomplete({ query, limit, offset }, options)` - Autocomplete search
+- `toCSV(rows)` - Export to CSV
+
+---
+
+## Environment-Based Content
+
+The platform uses an environment-based content model for publishing workflow:
+
+1. **dev** - Development environment (editable in constructor)
+2. **stage** - Staging/preview environment (for review before production)
+3. **production** - Live production environment (public-facing)
+
+### Content Flow
+
+```
+┌─────────┐    Save to Stage    ┌─────────┐    Publish    ┌────────────┐
+│   dev   │ ─────────────────── │  stage  │ ───────────── │ production │
+└─────────┘                     └─────────┘               └────────────┘
+     ▲
+     │
+ Constructor
+   edits
+```
+
+### Tables with Environment Column
+- `tour_pages` - Pages with `environment` column
+- `project_audio_tracks` - Audio tracks with `environment` column
+- `project_transition_settings` - CSS transition settings with `environment` column
+
+### Source Key Tracking
+When content is copied between environments, the `source_key` field stores the ID of the source record. This enables:
+- Tracking content lineage
+- Identifying which stage records came from dev
+- Rolling back changes if needed
+
+### Environment Access Control
+
+Access to content is controlled by environment with strict isolation:
+
+| Environment | Authentication | Access | Use Case |
+|-------------|----------------|--------|----------|
+| **dev** | Required (JWT) | Admin/Constructor only | Editing in constructor |
+| **stage** | Required (JWT) | Authenticated users | Review workspace before publish |
+| **production** | Public (no auth) | Anyone | Published public tours |
+
+**Security Layers:**
+
+1. **Backend Middleware** (`requireRuntimeReadOrAuth`): Only `production` environment allows unauthenticated GET requests. Stage and dev require JWT authentication.
+
+2. **Runtime Context API** (`getRuntimeEnvironment`): Blocks `dev` environment from being accessed via `X-Runtime-Environment` header. Only `production` and `stage` are allowed.
+
+3. **Database Filtering** (`applyRuntimeEnvironment`): Applies environment filter to all queries when runtime context is present.
+
+4. **Frontend Routes**:
+   - `/p/[slug]` → production (LayoutGuest)
+   - `/p/[slug]/stage` → stage (LayoutAuthenticated)
+   - `/constructor` → dev (LayoutAuthenticated)
+
+**Navigation uses `targetPageSlug`** (not `targetPageId`) in `ui_schema_json` to ensure navigation works correctly across environments since page IDs differ between dev, stage, and production.
+
+---
+
+## Data Types Reference
+
+| Sequelize Type | PostgreSQL Type | Usage |
+|----------------|-----------------|-------|
+| UUID | uuid | Primary keys, foreign keys |
+| TEXT | text | Long strings (unlimited) |
+| STRING(n) | varchar(n) | Limited strings |
+| INTEGER | integer | Whole numbers |
+| DECIMAL | numeric | Precise decimals |
+| BOOLEAN | boolean | True/false |
+| DATE | timestamp with time zone | Dates and times |
+| JSON | jsonb | Structured data |
+| ENUM | enum type | Fixed value sets |
+| VIRTUAL | (none) | Computed fields |
+
+---
+
+## Common Model Options
+
+Most models share these Sequelize options:
+```javascript
+{
+  timestamps: true,      // Adds createdAt, updatedAt
+  paranoid: true,        // Soft delete via deletedAt
+  freezeTableName: true, // Table name = model name
+}
+```
+
+**Exception:** The `file` model does not set `freezeTableName: true`, so its table name is `files` (pluralized by Sequelize default).
+
+All records include audit fields:
+- `createdAt` - Creation timestamp
+- `updatedAt` - Last modification timestamp
+- `deletedAt` - Soft deletion timestamp (null if not deleted)
+- `createdById` - Creating user's ID
+- `updatedById` - Last modifying user's ID
diff --git a/backend/docs/modules/auth.md b/backend/docs/modules/auth.md
new file mode 100644
index 0000000..b16fad2
--- /dev/null
+++ b/backend/docs/modules/auth.md
@@ -0,0 +1,942 @@
+# Backend Auth Module Documentation
+
+## Overview
+
+The Auth module provides comprehensive authentication and authorization for the application. It supports local email/password authentication, OAuth 2.0 (Google, Microsoft), JWT-based session management, email verification, and password reset flows.
+
+**Files:**
+| File | Purpose |
+|------|---------|
+| `src/auth/auth.ts` | Passport.js strategy configurations (JWT, Google, Microsoft) |
+| `src/services/auth.ts` | Auth business logic (signin, password reset/update, email verification) |
+| `src/routes/auth.ts` | REST API endpoints for authentication |
+| `src/helpers.ts` | JWT signing utility (`jwtSign`) |
+| `src/db/api/users.js` | User database operations (tokens, password updates) |
+| `src/middlewares/rateLimiter.js` | Auth-specific rate limiters |
+
+---
+
+## Architecture Diagram
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                         Frontend/Client                              │
+│  ┌────────────────┐  ┌────────────────┐  ┌────────────────────────┐  │
+│  │ Login Form     │  │ Signup Form    │  │ OAuth Buttons          │  │
+│  │ (email/pass)   │  │ (email/pass)   │  │ (Google/Microsoft)     │  │
+│  └───────┬────────┘  └───────┬────────┘  └───────────┬────────────┘  │
+└──────────┼───────────────────┼───────────────────────┼───────────────┘
+           │                   │                       │
+           ▼                   ▼                       ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                    Routes Layer (routes/auth.ts)                     │
+│                                                                      │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │ Rate Limiters:                                                │   │
+│  │  • authLimiter (10 req/15min) → /signin/local                │   │
+│  │  • passwordResetLimiter (5 req/hour) → /send-password-reset  │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+│                                                                      │
+│  ┌───────────────┐  ┌───────────────┐  ┌───────────────────────┐    │
+│  │ POST /signin  │  │ PUT /reset    │  │ GET /signin/google    │    │
+│  │   /local      │  │               │  │ GET /signin/microsoft │    │
+│  └───────┬───────┘  └───────┬───────┘  └───────────┬───────────┘    │
+│          │                  │                      │                 │
+└──────────┼──────────────────┼──────────────────────┼─────────────────┘
+           │                  │                      │
+           ▼                  ▼                      ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                  Service Layer (services/auth.ts)                    │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ Auth Class (Static Methods)                                    │  │
+│  │  • signup(email, password, options, host)                      │  │
+│  │  • signin(email, password)                                     │  │
+│  │  • verifyEmail(token)                                          │  │
+│  │  • passwordUpdate(currentPassword, newPassword, options)       │  │
+│  │  • passwordReset(token, password)                              │  │
+│  │  • sendEmailAddressVerificationEmail(email, host)              │  │
+│  │  • sendPasswordResetEmail(email, type, host)                   │  │
+│  │  • updateProfile(data, currentUser)                            │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────┘
+           │                  │                      │
+           ▼                  ▼                      ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│              Passport Layer (auth/auth.ts)                           │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐   │
+│  │ JWT Strategy    │  │ Google Strategy │  │ Microsoft Strategy  │   │
+│  │ (API Auth)      │  │ (OAuth 2.0)     │  │ (OAuth 2.0)         │   │
+│  └─────────────────┘  └─────────────────┘  └─────────────────────┘   │
+│                              │                      │                │
+│                              └──────────┬───────────┘                │
+│                                         │                            │
+│                              ┌──────────▼──────────┐                 │
+│                              │  socialStrategy()   │                 │
+│                              │  • findOrCreate     │                 │
+│                              │  • Generate JWT     │                 │
+│                              └─────────────────────┘                 │
+└──────────────────────────────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│               Database Layer (db/api/users.js)                       │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ UsersDBApi (Static Methods)                                    │  │
+│  │  • findBy({ email })                                           │  │
+│  │  • createFromAuth(data)                                        │  │
+│  │  • updatePassword(id, password)                                │  │
+│  │  • generateEmailVerificationToken(email)                       │  │
+│  │  • generatePasswordResetToken(email)                           │  │
+│  │  • findByEmailVerificationToken(token)                         │  │
+│  │  • findByPasswordResetToken(token)                             │  │
+│  │  • markEmailVerified(id)                                       │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Authentication Strategies
+
+### 1. JWT Strategy (Primary)
+
+Used for API authentication on all protected routes.
+
+**Configuration (auth/auth.ts):**
+```javascript
+passport.use(
+  new JWTstrategy({
+    passReqToCallback: true,
+    secretOrKey: config.secret_key,
+    jwtFromRequest: ExtractJWT.fromAuthHeaderAsBearerToken(),
+  }, async (req, token, done) => {
+    const user = await UsersDBApi.findBy({ email: token.user.email });
+
+    if (user && user.disabled) {
+      return done(new Error(`User '${user.email}' is disabled`));
+    }
+
+    req.currentUser = user;
+    return done(null, user);
+  })
+);
+```
+
+**Token Structure:**
+```javascript
+{
+  user: {
+    id: "uuid",
+    email: "user@example.com"
+  },
+  iat: 1234567890,  // Issued at
+  exp: 1234589490   // Expires in 6 hours
+}
+```
+
+**Usage:**
+```javascript
+// Protect route with JWT
+router.get('/me', passport.authenticate('jwt', { session: false }), handler);
+
+// Access user in handler
+const currentUser = req.currentUser;
+```
+
+### 2. Google OAuth Strategy
+
+**Configuration (auth/auth.ts):**
+```javascript
+passport.use(
+  new GoogleStrategy({
+    clientID: config.google.clientId,
+    clientSecret: config.google.clientSecret,
+    callbackURL: config.apiUrl + '/auth/signin/google/callback',
+    passReqToCallback: true,
+  }, (request, accessToken, refreshToken, profile, done) => {
+    socialStrategy(profile.email, profile, providers.GOOGLE, done);
+  })
+);
+```
+
+**Environment Variables:**
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_CLIENT_ID` | Google OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret |
+
+**OAuth Scopes:** `profile`, `email`
+
+### 3. Microsoft OAuth Strategy
+
+**Configuration (auth/auth.ts):**
+```javascript
+passport.use(
+  new MicrosoftStrategy({
+    clientID: config.microsoft.clientId,
+    clientSecret: config.microsoft.clientSecret,
+    callbackURL: config.apiUrl + '/auth/signin/microsoft/callback',
+    passReqToCallback: true,
+  }, (request, accessToken, refreshToken, profile, done) => {
+    const email = profile._json.mail || profile._json.userPrincipalName;
+    socialStrategy(email, profile, providers.MICROSOFT, done);
+  })
+);
+```
+
+**Environment Variables:**
+| Variable | Description |
+|----------|-------------|
+| `MS_CLIENT_ID` | Microsoft OAuth client ID |
+| `MS_CLIENT_SECRET` | Microsoft OAuth client secret |
+
+**OAuth Scopes:** `https://graph.microsoft.com/user.read`, `openid`
+
+### Social Strategy Helper
+
+Common logic for OAuth providers:
+
+```javascript
+function socialStrategy(email, profile, provider, done) {
+  db.users.findOrCreate({ where: { email, provider } }).then(([user]) => {
+    const body = {
+      id: user.id,
+      email: user.email,
+      name: profile.displayName,
+    };
+    const token = helpers.jwtSign({ user: body });
+    return done(null, { token });
+  });
+}
+```
+
+---
+
+## File Details
+
+### 1. services/auth.ts
+
+Core authentication business logic.
+
+#### Class: Auth
+
+```typescript
+class Auth {
+  static async signin(email, password)
+  static async verifyEmail(token, options)
+  static async passwordUpdate(currentPassword, newPassword, options)
+  static async passwordReset(token, password, options)
+  static async sendEmailAddressVerificationEmail(email, host)
+  static async sendPasswordResetEmail(email, type, host)
+  static async updateProfile(data, currentUser)
+}
+```
+
+#### Method: signup(email, password, options, host)
+
+Registers a new user or updates password for existing unverified user.
+
+**Flow:**
+```
+1. Check if user exists by email
+   ├── User exists with authenticationUid → Error: emailAlreadyInUse
+   ├── User exists but disabled → Error: userDisabled
+   └── User exists without authenticationUid → Update password
+2. If new user:
+   ├── Hash password (bcrypt, 12 rounds)
+   ├── Create user via UsersDBApi.createFromAuth()
+   └── Assign default "User" role
+3. Send verification email (if EmailSender configured)
+4. Return signed JWT token
+```
+
+**Returns:** JWT token string
+
+#### Method: signin(email, password)
+
+Authenticates user with email and password.
+
+**Flow:**
+```
+1. Find user by email
+   └── Not found → Error: userNotFound
+2. Check if disabled
+   └── Disabled → Error: userDisabled
+3. Verify password exists
+   └── No password → Error: wrongPassword
+4. Check email verification
+   └── Not verified (and email configured) → Error: userNotVerified
+5. Compare password with bcrypt
+   └── Mismatch → Error: wrongPassword
+6. Return signed JWT token
+```
+
+**Returns:** JWT token string
+
+#### Method: verifyEmail(token, options)
+
+Verifies user email address using token.
+
+**Flow:**
+```
+1. Find user by email verification token
+   └── Not found or expired → Error: invalidToken
+2. Mark email as verified
+3. Return true
+```
+
+#### Method: passwordUpdate(currentPassword, newPassword, options)
+
+Updates password for authenticated user.
+
+**Flow:**
+```
+1. Verify currentUser exists
+   └── Not authenticated → ForbiddenError
+2. Verify current password matches
+   └── Mismatch → Error: wrongPassword
+3. Verify new password is different
+   └── Same → Error: samePassword
+4. Hash new password and update
+```
+
+#### Method: passwordReset(token, password, options)
+
+Resets password using reset token.
+
+**Flow:**
+```
+1. Find user by password reset token
+   └── Not found or expired → Error: invalidToken
+2. Hash new password
+3. Update user password
+```
+
+---
+
+### 2. routes/auth.ts (327 lines)
+
+REST API endpoints for authentication.
+
+#### Endpoints Overview
+
+| Method | Path | Auth | Rate Limit | Description |
+|--------|------|------|------------|-------------|
+| POST | `/signin/local` | No | authLimiter | Login with email/password |
+| GET | `/me` | JWT | - | Get current user |
+| PUT | `/password-reset` | No | - | Reset password with token |
+| PUT | `/password-update` | JWT | - | Change password |
+| PUT | `/profile` | JWT | - | Update user profile |
+| PUT | `/verify-email` | No | - | Verify email with token |
+| POST | `/send-email-address-verification-email` | JWT | - | Resend verification email |
+| POST | `/send-password-reset-email` | No | passwordResetLimiter | Send password reset email |
+| GET | `/email-configured` | No | - | Check if email is configured |
+| GET | `/signin/google` | No | - | Initiate Google OAuth |
+| GET | `/signin/google/callback` | No | - | Google OAuth callback |
+| GET | `/signin/microsoft` | No | - | Initiate Microsoft OAuth |
+| GET | `/signin/microsoft/callback` | No | - | Microsoft OAuth callback |
+
+#### POST /api/auth/signin/local
+
+Login with email and password.
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword123"
+}
+```
+
+**Response (200):**
+```json
+"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+**Errors:**
+| Code | Message | Cause |
+|------|---------|-------|
+| 400 | `auth.userNotFound` | User doesn't exist |
+| 400 | `auth.userDisabled` | User account is disabled |
+| 400 | `auth.wrongPassword` | Invalid password |
+| 400 | `auth.userNotVerified` | Email not verified |
+| 429 | Too Many Requests | Rate limit exceeded |
+
+#### Self-Registration
+
+Self-registration is disabled. `POST /api/auth/signup` is not registered.
+New users are created through the authenticated Users flow and receive an
+invitation/setup link.
+
+#### GET /api/auth/me
+
+Get current authenticated user.
+
+**Headers:**
+```
+Authorization: Bearer <JWT_TOKEN>
+```
+
+**Response (200):**
+```json
+{
+  "id": "uuid",
+  "email": "user@example.com",
+  "firstName": "John",
+  "lastName": "Doe",
+  "emailVerified": true,
+  "disabled": false,
+  "app_role": {
+    "id": "uuid",
+    "name": "Administrator",
+    "permissions": [...]
+  },
+  "custom_permissions": [],
+  "avatar": [...],
+  "createdAt": "2024-01-01T00:00:00.000Z"
+}
+```
+
+**Note:** Password field is omitted from response.
+
+#### PUT /api/auth/password-reset
+
+Reset password using token from email.
+
+**Request:**
+```json
+{
+  "token": "abc123...",
+  "password": "newSecurePassword456"
+}
+```
+
+**Response (200):**
+```json
+{ "success": true }
+```
+
+#### PUT /api/auth/password-update
+
+Change password for authenticated user.
+
+**Headers:**
+```
+Authorization: Bearer <JWT_TOKEN>
+```
+
+**Request:**
+```json
+{
+  "currentPassword": "oldPassword123",
+  "newPassword": "newPassword456"
+}
+```
+
+**Errors:**
+| Code | Message | Cause |
+|------|---------|-------|
+| 400 | `auth.wrongPassword` | Current password incorrect |
+| 400 | `auth.passwordUpdate.samePassword` | New password same as old |
+| 403 | Forbidden | Not authenticated |
+
+#### PUT /api/auth/profile
+
+Update user profile.
+
+**Headers:**
+```
+Authorization: Bearer <JWT_TOKEN>
+```
+
+**Request:**
+```json
+{
+  "profile": {
+    "firstName": "John",
+    "lastName": "Smith",
+    "phoneNumber": "+1234567890"
+  }
+}
+```
+
+#### OAuth Endpoints
+
+**GET /api/auth/signin/google**
+- Redirects to Google OAuth consent screen
+- Query param: `app` (passed as state)
+
+**GET /api/auth/signin/google/callback**
+- Handles Google OAuth callback
+- Redirects to: `{uiUrl}/login?token={jwt}`
+
+**GET /api/auth/signin/microsoft**
+- Redirects to Microsoft OAuth consent screen
+- Query param: `app` (passed as state)
+
+**GET /api/auth/signin/microsoft/callback**
+- Handles Microsoft OAuth callback
+- Redirects to: `{uiUrl}/login?token={jwt}`
+
+---
+
+### 3. helpers.js (32 lines)
+
+JWT and utility functions.
+
+#### Method: jwtSign(data)
+
+Signs JWT token with application secret.
+
+```javascript
+static jwtSign(data) {
+  return jwt.sign(data, config.secret_key, { expiresIn: '6h' });
+}
+```
+
+**Configuration:**
+| Setting | Value | Description |
+|---------|-------|-------------|
+| Secret Key | `config.secret_key` | From `SECRET_KEY` env var |
+| Expiration | `6h` | Token valid for 6 hours |
+| Algorithm | `HS256` | Default HMAC SHA-256 |
+
+---
+
+### 4. db/api/users.js (Authentication Methods)
+
+User database operations related to authentication.
+
+#### Method: createFromAuth(data)
+
+Creates new user during signup.
+
+```javascript
+static async createFromAuth(data, options) {
+  const users = await db.users.create({
+    email: data.email,
+    firstName: data.firstName,
+    authenticationUid: data.authenticationUid,
+    password: data.password,
+  }, { transaction });
+
+  // Assign default "User" role
+  const app_role = await db.roles.findOne({
+    where: { name: config.roles?.user || 'User' },
+  });
+  await users.setApp_role(app_role?.id);
+
+  return users;
+}
+```
+
+#### Method: generateEmailVerificationToken(email)
+
+Generates secure token for email verification.
+
+```javascript
+static async generateEmailVerificationToken(email, options) {
+  const token = crypto.randomBytes(20).toString('hex');
+  const tokenExpiresAt = Date.now() + (24 * 60 * 60 * 1000); // 24 hours
+
+  await users.update({
+    emailVerificationToken: token,
+    emailVerificationTokenExpiresAt: tokenExpiresAt,
+  });
+
+  return token;
+}
+```
+
+**Token Properties:**
+| Property | Value |
+|----------|-------|
+| Length | 40 hex characters |
+| Expiry | 24 hours |
+| Storage | `emailVerificationToken` column |
+
+#### Method: generatePasswordResetToken(email)
+
+Generates secure token for password reset.
+
+Same implementation as `generateEmailVerificationToken` but stores in:
+- `passwordResetToken`
+- `passwordResetTokenExpiresAt`
+
+#### Method: findByEmailVerificationToken(token)
+
+Finds user by valid (non-expired) verification token.
+
+```javascript
+static async findByEmailVerificationToken(token, options) {
+  return db.users.findOne({
+    where: {
+      emailVerificationToken: token,
+      emailVerificationTokenExpiresAt: {
+        [Op.gt]: Date.now(),
+      },
+    },
+  });
+}
+```
+
+#### Method: markEmailVerified(id)
+
+Marks user email as verified.
+
+```javascript
+static async markEmailVerified(id, options) {
+  const users = await db.users.findByPk(id);
+  await users.update({ emailVerified: true });
+  return true;
+}
+```
+
+---
+
+## Rate Limiting
+
+Authentication endpoints have dedicated rate limiters defined in `middlewares/rateLimiter.js`.
+
+### Auth Limiter (Login)
+
+```javascript
+const authLimiter = createRateLimiter({
+  keyPrefix: 'auth',
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 10,
+  message: 'Too many authentication attempts. Please try again later.',
+  skipFailedRequests: false, // Count ALL attempts
+});
+```
+
+| Setting | Value |
+|---------|-------|
+| Window | 15 minutes |
+| Max Requests | 10 |
+| Applied To | `/signin/local` |
+
+### Signup Limiter
+
+Self-registration is disabled, so no signup limiter is registered.
+
+### Password Reset Limiter
+
+```javascript
+const passwordResetLimiter = createRateLimiter({
+  keyPrefix: 'password-reset',
+  windowMs: 60 * 60 * 1000, // 1 hour
+  max: 5,
+  message: 'Too many password reset requests. Please try again later.',
+});
+```
+
+| Setting | Value |
+|---------|-------|
+| Window | 1 hour |
+| Max Requests | 5 |
+| Applied To | `/send-password-reset-email` |
+
+### Rate Limit Response
+
+```json
+{
+  "error": "Too Many Requests",
+  "message": "Too many authentication attempts. Please try again later.",
+  "retryAfter": 300
+}
+```
+
+**Headers:**
+```
+X-RateLimit-Limit: 10
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 2024-01-01T00:15:00.000Z
+Retry-After: 300
+```
+
+---
+
+## Password Security
+
+### Hashing Configuration
+
+```javascript
+// config.ts
+bcrypt: {
+  saltRounds: 12,
+}
+```
+
+| Setting | Value | Security Impact |
+|---------|-------|-----------------|
+| Algorithm | bcrypt | Industry standard |
+| Salt Rounds | 12 | ~200ms hash time |
+| Salt | Auto-generated | Per-password unique |
+
+### Password Validation
+
+Passwords are:
+1. Hashed before storage (never stored in plain text)
+2. Compared using `bcrypt.compare()` (timing-attack safe)
+3. Required for local authentication
+
+---
+
+## Email Integration
+
+Email functionality is conditional based on configuration.
+
+### Email Configuration Check
+
+```javascript
+if (EmailSender.isConfigured) {
+  await this.sendEmailAddressVerificationEmail(user.email, host);
+}
+```
+
+When email is NOT configured:
+- Signup succeeds without verification email
+- Users are auto-verified on signin
+- Password reset emails not sent
+
+### Verification Email
+
+**Email Class:** `EmailAddressVerificationEmail`
+
+**Link Format:**
+```
+{host}/verify-email?token={token}
+```
+
+### Password Reset Email
+
+**Email Classes:**
+- `PasswordResetEmail` - Standard reset
+- `InvitationEmail` - New user invitation
+
+**Link Format:**
+```
+{host}/password-reset?token={token}
+```
+
+---
+
+## Configuration Reference
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SECRET_KEY` | Yes | `88dbeaf8-e906-405e-9e41-c3baadeda5c6` | JWT signing secret |
+| `GOOGLE_CLIENT_ID` | No | - | Google OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | No | - | Google OAuth client secret |
+| `MS_CLIENT_ID` | No | - | Microsoft OAuth client ID |
+| `MS_CLIENT_SECRET` | No | - | Microsoft OAuth client secret |
+| `ADMIN_EMAIL` | No | `admin@flatlogic.com` | Default admin email |
+| `ADMIN_PASS` | No | `88dbeaf8` | Default admin password |
+| `USER_PASS` | No | `c3baadeda5c6` | Default user password |
+
+### config.ts Settings
+
+```javascript
+{
+  bcrypt: { saltRounds: 12 },
+  secret_key: env.SECRET_KEY,
+  providers: {
+    LOCAL: 'local',
+    GOOGLE: 'google',
+    MICROSOFT: 'microsoft',
+  },
+  google: {
+    clientId: env.GOOGLE_CLIENT_ID,
+    clientSecret: env.GOOGLE_CLIENT_SECRET,
+  },
+  microsoft: {
+    clientId: env.MS_CLIENT_ID,
+    clientSecret: env.MS_CLIENT_SECRET,
+  },
+  roles: {
+    admin: 'Administrator',
+    user: 'Analytics Viewer',
+  },
+}
+```
+
+---
+
+## Authentication Flows
+
+### Local Login Flow
+
+```
+┌────────┐     ┌─────────┐     ┌─────────────┐     ┌──────────┐
+│ Client │────▶│ Router  │────▶│ AuthService │────▶│ UsersDB  │
+└────────┘     └─────────┘     └─────────────┘     └──────────┘
+    │               │                │                   │
+    │ POST /signin  │                │                   │
+    │ {email,pass}  │                │                   │
+    │──────────────▶│                │                   │
+    │               │ signin()       │                   │
+    │               │───────────────▶│                   │
+    │               │                │ findBy({email})   │
+    │               │                │──────────────────▶│
+    │               │                │◀──────────────────│
+    │               │                │                   │
+    │               │                │ bcrypt.compare()  │
+    │               │                │                   │
+    │               │                │ jwtSign()         │
+    │               │◀───────────────│                   │
+    │◀──────────────│                │                   │
+    │   JWT Token   │                │                   │
+```
+
+### OAuth Login Flow
+
+```
+┌────────┐     ┌─────────┐     ┌──────────┐     ┌──────────┐
+│ Client │     │ Backend │     │ Provider │     │ UsersDB  │
+└────────┘     └─────────┘     └──────────┘     └──────────┘
+    │               │                │                │
+    │ GET /signin/  │                │                │
+    │   google      │                │                │
+    │──────────────▶│                │                │
+    │               │ Redirect to    │                │
+    │◀──────────────│ consent screen │                │
+    │──────────────────────────────▶│                │
+    │               │                │                │
+    │               │  User consents │                │
+    │◀──────────────────────────────│                │
+    │               │                │                │
+    │ GET /callback │                │                │
+    │ ?code=...     │                │                │
+    │──────────────▶│                │                │
+    │               │ Exchange code  │                │
+    │               │───────────────▶│                │
+    │               │ Profile data   │                │
+    │               │◀───────────────│                │
+    │               │                │                │
+    │               │ findOrCreate() │                │
+    │               │───────────────────────────────▶│
+    │               │◀───────────────────────────────│
+    │               │ jwtSign()      │                │
+    │               │                │                │
+    │ Redirect to   │                │                │
+    │ /login?token= │                │                │
+    │◀──────────────│                │                │
+```
+
+### Email Verification Flow
+
+```
+┌────────┐     ┌─────────┐     ┌─────────────┐     ┌───────┐
+│ Client │     │ Router  │     │ AuthService │     │ Email │
+└────────┘     └─────────┘     └─────────────┘     └───────┘
+    │               │                │                │
+    │ POST /signup  │                │                │
+    │──────────────▶│                │                │
+    │               │ signup()       │                │
+    │               │───────────────▶│                │
+    │               │                │ generateToken()│
+    │               │                │ sendEmail()    │
+    │               │                │───────────────▶│
+    │               │◀───────────────│                │
+    │◀──────────────│                │                │
+    │   JWT Token   │                │                │
+    │               │                │                │
+    │   User clicks email link       │                │
+    │               │                │                │
+    │ PUT /verify-  │                │                │
+    │   email       │                │                │
+    │ {token}       │                │                │
+    │──────────────▶│                │                │
+    │               │ verifyEmail()  │                │
+    │               │───────────────▶│                │
+    │               │                │ markVerified() │
+    │               │◀───────────────│                │
+    │◀──────────────│                │                │
+    │   Success     │                │                │
+```
+
+---
+
+## Error Codes
+
+| Error Key | HTTP Status | Description |
+|-----------|-------------|-------------|
+| `auth.userNotFound` | 400 | User with email doesn't exist |
+| `auth.userDisabled` | 400 | User account is disabled |
+| `auth.wrongPassword` | 400 | Password doesn't match |
+| `auth.userNotVerified` | 400 | Email not verified |
+| `auth.emailAlreadyInUse` | 400 | Email already registered |
+| `auth.passwordUpdate.samePassword` | 400 | New password same as current |
+| `auth.passwordReset.error` | 400 | Token generation failed |
+| `auth.passwordReset.invalidToken` | 400 | Invalid or expired reset token |
+| `auth.emailAddressVerificationEmail.error` | 400 | Verification email failed |
+| `auth.emailAddressVerificationEmail.invalidToken` | 400 | Invalid verification token |
+
+---
+
+## Security Considerations
+
+1. **Password Storage:** bcrypt with 12 salt rounds
+2. **JWT Expiration:** 6 hours (balances security and UX)
+3. **Token Generation:** crypto.randomBytes(20) - 160-bit entropy
+4. **Token Expiry:** 24 hours for email/password reset tokens
+5. **Rate Limiting:** Prevents brute force attacks
+6. **Disabled User Check:** Checked on both JWT validation and login
+7. **Session-less:** No server-side session storage (stateless JWT)
+8. **HTTPS Required:** OAuth callbacks require HTTPS in production
+
+---
+
+## Testing
+
+### Test Local Login
+
+```bash
+curl -X POST http://localhost:3000/api/auth/signin/local \
+  -H "Content-Type: application/json" \
+  -d '{"email": "admin@flatlogic.com", "password": "password"}'
+```
+
+### Test Get Current User
+
+```bash
+curl http://localhost:3000/api/auth/me \
+  -H "Authorization: Bearer <JWT_TOKEN>"
+```
+
+### User Creation
+
+Use the authenticated Users API/UI to create invited users.
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `passport` | ^0.6.0 | Authentication middleware |
+| `passport-jwt` | ^4.0.0 | JWT strategy for Passport |
+| `passport-google-oauth2` | ^0.2.0 | Google OAuth strategy |
+| `passport-microsoft` | ^2.0.0 | Microsoft OAuth strategy |
+| `@types/passport-jwt` | ^4.0.1 | Maintained TypeScript definitions for JWT Passport strategy |
+| `@types/passport-google-oauth2` | ^0.1.10 | Maintained TypeScript definitions for Google OAuth Passport strategy |
+| `@types/passport-microsoft` | ^2.1.1 | Maintained TypeScript definitions for Microsoft Passport strategy |
+| `jsonwebtoken` | ^9.0.0 | JWT sign/verify |
+| `bcrypt` | ^5.1.0 | Password hashing |
+| `crypto` | built-in | Token generation |
+
+---
+
+## Summary
+
+The Auth module provides:
+
+1. **JWT Authentication** - Stateless API authentication with 6-hour tokens
+2. **Local Login** - Email/password authentication with bcrypt
+3. **OAuth 2.0** - Google and Microsoft social login
+4. **Email Verification** - Token-based email confirmation
+5. **Password Reset** - Secure token-based password recovery
+6. **Rate Limiting** - Protection against brute force attacks
+7. **Profile Management** - User profile updates
+8. **Role Assignment** - Default role on signup
diff --git a/backend/docs/modules/core.md b/backend/docs/modules/core.md
new file mode 100644
index 0000000..2126472
--- /dev/null
+++ b/backend/docs/modules/core.md
@@ -0,0 +1,781 @@
+# Core Module Documentation
+
+The Core module provides the foundational components of the backend application: the entry point, configuration management, and utility functions.
+
+## Overview
+
+| File | Purpose | Lines |
+|------|---------|-------|
+| `src/index.ts` | Application entry point, Express setup, middleware, route mounting | varies |
+| `src/config.ts` | Environment configuration and settings | varies |
+| `src/helpers.js` | Utility functions (wrapAsync, JWT, validation) | 32 |
+| `src/types/` | Shared strict TypeScript contracts for migrated backend code | varies |
+| `src/load-env.ts` | Central backend `.env` bootstrap for app and DB entrypoints | varies |
+
+---
+
+## 1. Application Entry Point (`index.ts`)
+
+### Purpose
+
+The main entry point that bootstraps the Express application, configures middleware, mounts routes, and starts the HTTP server.
+
+### Dependencies
+
+```typescript
+import bodyParser from 'body-parser';
+import cors from 'cors';
+import express from 'express';
+import helmet from 'helmet';
+import * as swaggerUI from 'swagger-ui-express';
+
+import { authenticateJwt, authenticateJwtWithCallback } from './auth/passport-middleware.ts';
+import config from './config.ts';
+import { wrapAsync } from './helpers.ts';
+import { runtimeContextMiddleware } from './middlewares/runtime-context.ts';
+import { downloadLimiter, searchLimiter, uploadLimiter } from './middlewares/rateLimiter.ts';
+import { createOpenApiDocument } from './openapi/document.ts';
+import {
+  exitAfterLogging,
+  logger,
+  registerProcessErrorHandlers,
+  requestLogger,
+} from './utils/logger.ts';
+```
+
+> TypeScript migration note: `index.ts`, `config.ts`, `helpers.ts`, `middlewares/validate-request.ts`, `middlewares/runtime-context.ts`, `middlewares/runtime-public.ts`, `routes/runtime-context.ts`, `validators/request-schemas.ts`, `services/notifications/list.ts`, `services/notifications/helpers.ts`, `utils/logger.ts`, and `utils/env-validation.ts` are now migrated runtime TypeScript modules. New migrated backend TypeScript files use `backend/tsconfig.json` with `strict: true`, reusable named types from `src/types/`, and lint rules that reject `any`, non-null assertions, and unsafe type assertions.
+
+> Environment bootstrap note: `src/load-env.ts` is loaded by app config and DB entrypoints so short backend scripts can see `backend/.env` without repeating `NODE_OPTIONS=-r dotenv/config`. If `NODE_ENV` is absent, it defaults to `dev_stage`, matching the standard VM backend flow.
+
+### Application Bootstrap Sequence
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    APPLICATION BOOTSTRAP                        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. EXPRESS INITIALIZATION                                       │
+│    • Create Express app                                         │
+│    • Enable trust proxy (for reverse proxies)                   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. SECURITY MIDDLEWARE                                          │
+│    • Helmet (CSP disabled, COEP disabled)                       │
+│    • CORS (origin: true - allow all origins)                    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 3. AUTHENTICATION SETUP                                         │
+│    • Load Passport strategies (JWT, Google, Microsoft)          │
+│    • Create jwtAuth middleware                                  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 4. LOGGING                                                      │
+│    • Register process-level error handlers                      │
+│    • Apply requestLogger middleware (early for full coverage)   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 5. FILE ROUTES (BEFORE BODY PARSER)                             │
+│    • Mount file routes without JSON parsing                     │
+│    • Apply rate limiters (download: 200/min, upload: 10/min)    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 6. BODY PARSING                                                 │
+│    • JSON parser (1MB limit)                                    │
+│    • URL-encoded parser (1MB limit)                             │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 7. RUNTIME CONTEXT                                              │
+│    • Apply runtimeContextMiddleware                             │
+│    • Detect environment from X-Runtime-Environment header       │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 8. ROUTE MOUNTING                                               │
+│    • Public routes (health, auth, runtime-context)              │
+│    • Protected routes (JWT required)                            │
+│    • Runtime public routes (production content without auth)    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 9. STATIC FILES & ERROR HANDLING                                │
+│    • Serve public directory if exists                           │
+│    • Generic error handler                                      │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 10. SERVER START                                                │
+│    • Listen on PORT (8080 or 3000 for dev_stage)                │
+│    • Log startup message                                        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Middleware Stack
+
+```javascript
+// Order matters - applied in this sequence:
+
+1. swaggerUI.serve          // API documentation at /api-docs
+2. helmet()                 // Security headers
+3. cors({ origin: true })   // Cross-origin requests
+4. requestLogger            // Request logging (Pino)
+5. downloadLimiter          // Rate limit for /api/file/download, /api/file/presign
+6. uploadLimiter            // Rate limit for /api/file/upload*
+7. bodyParser.json()        // JSON parsing (1MB limit)
+8. bodyParser.urlencoded()  // Form data parsing
+9. runtimeContextMiddleware // Environment detection
+10. passport.authenticate() // JWT authentication (per-route)
+11. checkPermissions        // RBAC (per-route)
+12. errorHandler            // Generic error handling
+```
+
+### Route Mounting
+
+#### Public Routes (No Authentication)
+
+```javascript
+app.get('/api/health', ...)           // Health check
+app.use('/api/auth', authRoutes)      // Authentication
+app.use('/api/runtime-context', ...)  // Runtime context
+app.use('/api/file', fileRoutes)      // File download/presign (partial)
+```
+
+#### Protected Routes (JWT Required)
+
+```javascript
+app.use('/api/users', jwtAuth, usersRoutes)
+app.use('/api/roles', jwtAuth, rolesRoutes)
+app.use('/api/permissions', jwtAuth, permissionsRoutes)
+app.use('/api/project_memberships', jwtAuth, project_membershipsRoutes)
+app.use('/api/assets', jwtAuth, assetsRoutes)
+app.use('/api/asset_variants', jwtAuth, asset_variantsRoutes)
+app.use('/api/presigned_url_requests', jwtAuth, presigned_url_requestsRoutes)
+app.use('/api/publish_events', jwtAuth, publish_eventsRoutes)
+app.use('/api/pwa_caches', jwtAuth, pwa_cachesRoutes)
+app.use('/api/access_logs', jwtAuth, access_logsRoutes)
+app.use('/api/element-type-defaults', jwtAuth, element_type_defaultsRoutes)
+app.use('/api/ui-elements', jwtAuth, element_type_defaultsRoutes)  // Alias
+app.use('/api/project-element-defaults', jwtAuth, project_element_defaultsRoutes)
+app.use('/api/publish', jwtAuth, publishRoutes)
+app.use('/api/search', jwtAuth, searchLimiter, searchRoutes)
+```
+
+#### Runtime Public Routes (Production Content Without Auth)
+
+```javascript
+// These routes use requireRuntimeReadOrAuth middleware
+// Allows unauthenticated GET requests in production environment
+
+mountRuntimeEntityRoute('/api/projects', 'projects', projectsRoutes)
+mountRuntimeEntityRoute('/api/tour_pages', 'tour_pages', tour_pagesRoutes)
+mountRuntimeEntityRoute('/api/project_audio_tracks', 'project_audio_tracks', project_audio_tracksRoutes)
+```
+
+### Key Functions
+
+#### `requireRuntimeReadOrAuth`
+
+Middleware that allows public read access for production content:
+
+```javascript
+const requireRuntimeReadOrAuth = (req, res, next) => {
+  const headerEnvironment = req.runtimeContext?.headerEnvironment;
+  const isReadOnlyRequest = ['GET', 'OPTIONS'].includes(req.method);
+  const hasAuthHeader = Boolean(req.headers.authorization);
+
+  // Only production is public. Stage requires authentication.
+  const isPublicEnvironment = headerEnvironment === 'production';
+
+  if (isPublicEnvironment && isReadOnlyRequest && !hasAuthHeader) {
+    req.isRuntimePublicRequest = true;
+    return next();  // Allow without JWT
+  }
+
+  req.isRuntimePublicRequest = false;
+  return jwtAuth(req, res, next);  // Require JWT
+};
+```
+
+#### `mountRuntimeEntityRoute`
+
+Helper to mount routes with runtime public access middleware stack:
+
+```javascript
+const mountRuntimeEntityRoute = (path, entityName, router) => {
+  app.use(
+    path,
+    requireRuntimeReadOrAuth,              // JWT or public production
+    blockNonPublicRuntimeListEndpoints,    // Block non-list for public
+    sanitizePublicRuntimeListResponse(entityName),  // Filter sensitive fields
+    router,
+  );
+};
+```
+
+#### `getBaseUrl`
+
+Utility to extract base URL for Swagger:
+
+```javascript
+const getBaseUrl = (url) => {
+  if (!url) return '';
+  return url.endsWith('/api') ? url.slice(0, -4) : url;
+};
+```
+
+### Health Check Endpoint
+
+```javascript
+GET /api/health
+
+// Response (200 - healthy):
+{
+  "status": "ok",
+  "timestamp": "2026-03-30T12:00:00.000Z",
+  "uptime": 12345.678,
+  "environment": "production",
+  "database": "connected"
+}
+
+// Response (503 - degraded):
+{
+  "status": "degraded",
+  "timestamp": "2026-03-30T12:00:00.000Z",
+  "uptime": 12345.678,
+  "environment": "production",
+  "database": "disconnected",
+  "databaseError": "Connection refused"
+}
+```
+
+### Swagger/OpenAPI Configuration
+
+```javascript
+const specs = createOpenApiDocument({
+  serverUrl: config.server.swaggerServerUrl,
+});
+
+app.use('/api-docs', swaggerUI.serve, swaggerUI.setup(specs));
+```
+
+The canonical OpenAPI source is `backend/src/openapi/document.ts`. It defines
+shared schemas, common responses and parameters, generated factory CRUD paths,
+and explicit custom-route paths. Route-local JSDoc comments are not the source
+of truth for Swagger UI.
+
+### Error Handler
+
+```javascript
+app.use((err, req, res, _next) => {
+  if (!res.headersSent) {
+    const requestLog = getRequestLogger(req) ?? logger;
+    requestLog.error(
+      { err, url: req.url, method: req.method },
+      'Express error middleware caught unhandled error',
+    );
+    res.status(safeStatusCode).json({
+      message:
+        safeStatusCode === 503
+          ? 'Service temporarily unavailable'
+          : 'Internal server error',
+    });
+  }
+});
+```
+
+Route-level `commonErrorHandler` also uses the request-scoped logger when
+available and logs unexpected route failures as `Route handler failed`. Circuit
+breaker rejections use status `503` instead of being collapsed to `500`.
+
+### Server Configuration
+
+```javascript
+const PORT = config.server.port;
+
+const server = app.listen(PORT, () => {
+  logger.info(
+    { port: PORT, env: config.server.env },
+    'Server started',
+  );
+});
+
+server.on('error', (err) => {
+  logger.error(
+    { err, port: PORT, env: config.server.env },
+    'Server failed to start',
+  );
+  exitAfterLogging();
+});
+```
+
+Startup errors such as `EADDRINUSE` happen on the Node `Server`, outside the
+Express request lifecycle, so the generic Express error middleware cannot catch
+them. The server-level `error` listener logs the failure and exits with a
+non-zero status for nodemon/PM2 supervision.
+
+---
+
+## 2. Configuration (`config.ts`)
+
+### Purpose
+
+Centralized configuration management with environment variable support and sensible defaults.
+
+### Configuration Structure
+
+```javascript
+const config = {
+  // Google Cloud Storage
+  gcloud: {
+    bucket: 'fldemo-files',
+    hash: 'afeefb9d49f5b7977577876b99532ac7',
+    projectId: env.GC_PROJECT_ID,
+    clientEmail: env.GC_CLIENT_EMAIL,
+    privateKey: env.GC_PRIVATE_KEY,
+  },
+  fileStorage: {
+    provider: env.FILE_STORAGE_PROVIDER,
+  },
+
+  // AWS S3
+  s3: {
+    bucket: env.AWS_S3_BUCKET,
+    region: env.AWS_S3_REGION,
+    accessKeyId: env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+    prefix: env.AWS_S3_PREFIX,
+    connectionTimeout: env.AWS_S3_CONNECTION_TIMEOUT,
+    requestTimeout: env.AWS_S3_REQUEST_TIMEOUT,
+    maxAttempts: env.AWS_S3_MAX_ATTEMPTS,
+    maxSockets: env.AWS_S3_MAX_SOCKETS,
+    keepAlive: env.AWS_S3_KEEP_ALIVE !== 'false',
+    presignExpirySeconds: env.AWS_S3_PRESIGN_EXPIRY,
+  },
+
+  resilience: {
+    ffmpeg: {
+      reverseTimeoutMs: env.FFMPEG_REVERSE_TIMEOUT_MS,
+      ffprobeTimeoutMs: env.FFPROBE_TIMEOUT_MS,
+      breaker: {
+        failureThreshold: env.FFMPEG_BREAKER_FAILURE_THRESHOLD,
+        cooldownMs: env.FFMPEG_BREAKER_COOLDOWN_MS,
+        successThreshold: env.FFMPEG_BREAKER_SUCCESS_THRESHOLD,
+      },
+    },
+    fileStorage: {
+      breaker: {
+        failureThreshold: env.FILE_STORAGE_BREAKER_FAILURE_THRESHOLD,
+        cooldownMs: env.FILE_STORAGE_BREAKER_COOLDOWN_MS,
+        successThreshold: env.FILE_STORAGE_BREAKER_SUCCESS_THRESHOLD,
+      },
+    },
+  },
+
+  // Password hashing
+  bcrypt: {
+    saltRounds: 12,
+  },
+
+  // Default credentials
+  admin_pass: env.ADMIN_PASS,
+  user_pass: env.USER_PASS,
+  admin_email: env.ADMIN_EMAIL,
+
+  // Authentication providers
+  providers: {
+    LOCAL: 'local',
+    GOOGLE: 'google',
+    MICROSOFT: 'microsoft',
+  },
+
+  // JWT
+  secret_key: env.SECRET_KEY,
+
+  // Server URLs
+  remote: '',
+  port,
+  hostUI,
+  portUI,
+
+  // Swagger
+  swaggerUI,
+  swaggerPort,
+
+  // OAuth
+  google: {
+    clientId: env.GOOGLE_CLIENT_ID,
+    clientSecret: env.GOOGLE_CLIENT_SECRET,
+  },
+  microsoft: {
+    clientId: env.MS_CLIENT_ID,
+    clientSecret: env.MS_CLIENT_SECRET,
+  },
+
+  // File uploads
+  uploadDir: os.tmpdir(),
+
+  // Email (AWS SES)
+  email: {
+    from: 'Tour Builder Platform <app@flatlogic.app>',
+    host: 'email-smtp.us-east-1.amazonaws.com',
+    port: 587,
+    auth: {
+      user: env.EMAIL_USER,
+      pass: env.EMAIL_PASS,
+    },
+    tls: {
+      rejectUnauthorized: env.EMAIL_TLS_REJECT_UNAUTHORIZED !== 'false',
+    },
+  },
+
+  // Default roles
+  roles: {
+    admin: 'Administrator',
+    user: 'Analytics Viewer',
+  },
+  server: {
+    env: env.NODE_ENV,
+    port: serverPort,
+    swaggerServerUrl,
+  },
+
+};
+```
+
+### Environment Variables Reference
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `NODE_ENV` | string | `development` | Environment: `development`, `production`, `dev_stage`, `test` |
+| `PORT` | number | `8080` | Server port |
+| `SECRET_KEY` | string | UUID | JWT signing key (min 16 chars) |
+| `ADMIN_EMAIL` | string | `admin@flatlogic.com` | Admin user email |
+| `ADMIN_PASS` | string | Generated | Admin user password |
+| `USER_PASS` | string | Generated | Default user password |
+| `AWS_S3_BUCKET` | string | - | S3 bucket name |
+| `AWS_S3_REGION` | string | `us-east-1` | S3 region |
+| `AWS_ACCESS_KEY_ID` | string | - | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | string | - | AWS secret key |
+| `AWS_S3_PREFIX` | string | Hash | S3 key prefix |
+| `GOOGLE_CLIENT_ID` | string | - | Google OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | string | - | Google OAuth client secret |
+| `MS_CLIENT_ID` | string | - | Microsoft OAuth client ID |
+| `MS_CLIENT_SECRET` | string | - | Microsoft OAuth client secret |
+| `EMAIL_USER` | string | - | SMTP username |
+| `EMAIL_PASS` | string | - | SMTP password |
+| `EMAIL_TLS_REJECT_UNAUTHORIZED` | string | `true` | TLS validation |
+| `LOG_LEVEL` | string | `info` | Pino log level |
+
+### Environment Validation
+
+The configuration uses Joi schema validation via `utils/env-validation.js`:
+
+```javascript
+const Joi = require('joi');
+
+const envSchema = Joi.object({
+  NODE_ENV: Joi.string()
+    .valid('development', 'test', 'production', 'dev_stage')
+    .default('development'),
+
+  PORT: Joi.number().default(8080),
+
+  DB_HOST: Joi.string().default('localhost'),
+  DB_PORT: Joi.number().default(5432),
+  DB_NAME: Joi.string().default('db_tour_builder_platform'),
+  DB_USER: Joi.string().default('postgres'),
+  DB_PASS: Joi.string().allow('').default(''),
+
+  SECRET_KEY: Joi.string()
+    .min(16)
+    .default('88dbeaf8-e906-405e-9e41-c3baadeda5c6'),
+
+  // ... more validations
+}).unknown(true);
+
+function validateEnv() {
+  const { error, value } = envSchema.validate(process.env, {
+    abortEarly: false,
+    stripUnknown: false,
+  });
+
+  if (error) {
+    const messages = error.details.map((d) => `  - ${d.message}`);
+    logger.error({ errors: messages }, 'Environment validation failed');
+
+    if (process.env.NODE_ENV === 'production') {
+      process.exit(1);  // Fatal in production
+    } else {
+      logger.warn('Continuing with default values in non-production mode');
+    }
+  }
+
+  return value;
+}
+```
+
+---
+
+## 3. Helpers (`helpers.js`)
+
+### Purpose
+
+Utility class providing common functions used across the application.
+
+### Class Definition
+
+```javascript
+const jwt = require('jsonwebtoken');
+const config = require('./config');
+
+module.exports = class Helpers {
+  /**
+   * Wraps async route handlers to catch errors and pass to next()
+   * @param {Function} fn - Async function (req, res, next) => Promise
+   * @returns {Function} Wrapped function
+   */
+  static wrapAsync(fn) {
+    return function (req, res, next) {
+      fn(req, res, next).catch(next);
+    };
+  }
+
+  /**
+   * Common error handler middleware
+   * @param {Error} error - Error object with code/status property
+   * @param {Request} req - Express request
+   * @param {Response} res - Express response
+   * @param {Function} _next - Next middleware (unused)
+   */
+  static commonErrorHandler(error, req, res, _next) {
+    const statusCode = error.code || error.status;
+
+    // Known HTTP error codes - return error message
+    if ([400, 401, 403, 404, 409, 422, 503].includes(statusCode)) {
+      return res.status(statusCode).send(error.message);
+    }
+
+    // Unknown errors - log and return generic message
+    const requestLog = getRequestLogger(req) ?? logger;
+    requestLog.error({ err: error }, 'Route handler failed');
+    return res.status(500).send('Internal server error');
+  }
+
+  /**
+   * Sign JWT token with 6-hour expiration
+   * @param {Object} data - Payload to sign
+   * @returns {string} JWT token
+   */
+  static jwtSign(data) {
+    return jwt.sign(data, config.secret_key, { expiresIn: '6h' });
+  }
+
+  /**
+   * Validate UUID v4 format
+   * @param {string} value - String to validate
+   * @returns {boolean} True if valid UUID v4
+   */
+  static isUuidV4(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+      value,
+    );
+  }
+};
+```
+
+### Usage Examples
+
+#### wrapAsync
+
+```javascript
+// Without wrapAsync - need try/catch
+router.get('/', async (req, res, next) => {
+  try {
+    const data = await Service.findAll();
+    res.json(data);
+  } catch (error) {
+    next(error);
+  }
+});
+
+// With wrapAsync - cleaner code
+const wrapAsync = require('../helpers').wrapAsync;
+
+router.get('/', wrapAsync(async (req, res) => {
+  const data = await Service.findAll();
+  res.json(data);
+}));
+```
+
+#### commonErrorHandler
+
+```javascript
+const { commonErrorHandler } = require('../helpers');
+
+// At end of route file
+router.use('/', commonErrorHandler);
+
+// Errors with code/status are returned as-is
+const error = new Error('Not found');
+error.code = 404;
+throw error;  // → 404 "Not found"
+
+// Unknown errors return 500
+throw new Error('Database connection failed');  // → 500 "Internal server error"
+```
+
+#### jwtSign
+
+```javascript
+const { jwtSign } = require('./helpers');
+
+// Create JWT token
+const token = jwtSign({
+  user: {
+    id: user.id,
+    email: user.email,
+  },
+});
+
+// Token expires in 6 hours
+// Token is signed with config.secret_key
+```
+
+#### isUuidV4
+
+```javascript
+const { isUuidV4 } = require('./helpers');
+
+// Validate UUID format
+isUuidV4('550e8400-e29b-41d4-a716-446655440000');  // true
+isUuidV4('550e8400-e29b-31d4-a716-446655440000');  // false (version 3)
+isUuidV4('not-a-uuid');                             // false
+isUuidV4('');                                       // false
+```
+
+---
+
+## Module Dependencies
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        index.ts                                 │
+│                    (Application Entry)                          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+          ┌───────────────────┼───────────────────┐
+          ▼                   ▼                   ▼
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│   config.ts     │  │   helpers.ts    │  │  utils/logger   │
+│ (Configuration) │  │  (Utilities)    │  │   (Logging)     │
+└─────────────────┘  └─────────────────┘  └─────────────────┘
+          │                   │
+          ▼                   ▼
+┌─────────────────┐  ┌─────────────────┐
+│ env-validation  │  │  jsonwebtoken   │
+│    (Joi)        │  │   (JWT lib)     │
+└─────────────────┘  └─────────────────┘
+
+External Dependencies:
+  • express (web framework)
+  • cors (CORS middleware)
+  • helmet (security headers)
+  • passport (authentication)
+  • body-parser (request parsing)
+  • swagger-ui-express (API docs)
+  • jsonwebtoken (JWT signing)
+  • joi (schema validation)
+  • dotenv (environment loading)
+  • pino (logging)
+```
+
+---
+
+## Best Practices Implemented
+
+### 1. Environment Validation
+
+- Joi schema validates all environment variables at startup
+- Fails fast in production, warns in development
+- Provides sensible defaults for optional variables
+
+### 2. Security
+
+- Helmet middleware for security headers
+- CORS configured for cross-origin requests
+- JWT authentication with 6-hour expiration
+- Trust proxy enabled for reverse proxy support
+
+### 3. Error Handling
+
+- `wrapAsync` wrapper for async route handlers
+- Centralized error handler with status code mapping
+- Generic error handler logs and returns safe message
+
+### 4. Middleware Ordering
+
+- File routes mounted before body parser (binary uploads)
+- Rate limiters applied before routes
+- Authentication applied per-route (not globally)
+- Error handler at the end of middleware stack
+
+### 5. API Documentation
+
+- Swagger/OpenAPI 3.0 generated from `backend/src/openapi/document.ts`
+- Available at `/api-docs` endpoint
+- Security scheme documented (Bearer JWT)
+- `backend/tests/openapi-document.test.ts` checks key paths, factory CRUD
+  coverage, internal `$ref` resolution, and Swagger UI handler smoke behavior
+
+### 6. Logging
+
+- Pino structured logging
+- Request logger for all routes
+- Error logging with context (URL, method)
+
+---
+
+## Configuration Precedence
+
+```
+1. Environment Variables (process.env.*)
+   ↓ (fallback)
+2. .env file (loaded by dotenv)
+   ↓ (fallback)
+3. Joi schema defaults
+   ↓ (fallback)
+4. Hardcoded defaults in config.ts
+```
+
+---
+
+## Server Modes
+
+| NODE_ENV | Port | Database | Swagger | Description |
+|----------|------|----------|---------|-------------|
+| `development` | 8080 | Local | localhost:8080 | Legacy local development |
+| `dev_stage` | 3000 | Remote | localhost:3000 | Staging preview |
+| `production` | 8080 | Remote | Disabled | Production deployment |
+| `test` | 8080 | Test DB | Disabled | Automated testing |
+
+**Standard VM note:** the VM PM2 setup runs the backend with
+`NODE_ENV=dev_stage`, so the backend listens on port `3000`. The frontend runs
+separately on port `3001`, and Apache proxies public traffic from port `80`.
+Do not use `8080` as the VM backend health check unless the PM2 definition has
+been changed. See [deployment-vm.md](../../../documentation/deployment-vm.md).
diff --git a/backend/docs/modules/db-api.md b/backend/docs/modules/db-api.md
new file mode 100644
index 0000000..8173c1d
--- /dev/null
+++ b/backend/docs/modules/db-api.md
@@ -0,0 +1,1109 @@
+# Backend DB API Module
+
+## Overview
+
+The DB API module provides the data access layer that sits between services and Sequelize models. It encapsulates query logic, filtering, pagination, and data transformations using a declarative configuration pattern via the `GenericDBApi` base class.
+
+**Location:** `backend/src/db/api/`
+
+**Files:** 20 files (1 base class + 18 entity APIs + 1 utility)
+
+| File | Class/Purpose | LOC | Extends GenericDBApi |
+|------|---------------|-----|---------------------|
+| `base.api.ts` | `GenericDBApi` - Base class | 726 | - |
+| `users.ts` | `UsersDBApi` - User accounts | 979 | No (custom) |
+| `projects.ts` | `ProjectsDBApi` - Projects | ~320 | Yes |
+| `tour_pages.ts` | `Tour_pagesDBApi` - Tour pages | ~350 | Yes |
+| `assets.ts` | `AssetsDBApi` - Media assets | ~92 | Yes |
+| `asset_variants.ts` | `Asset_variantsDBApi` - Asset variants | 82 | Yes |
+| `roles.ts` | `RolesDBApi` - RBAC roles | 71 | Yes |
+| `permissions.ts` | `PermissionsDBApi` - RBAC permissions | 53 | Yes |
+| `project_memberships.ts` | `Project_membershipsDBApi` - Team access | 86 | Yes |
+| `element_type_defaults.ts` | `Element_type_defaultsDBApi` - Global defaults | ~409 | Yes |
+| `project_element_defaults.ts` | `Project_element_defaultsDBApi` - Project defaults | ~410 | Yes |
+| `project_audio_tracks.ts` | `Project_audio_tracksDBApi` - Audio tracks | ~199 | Yes |
+| `project_transition_settings.ts` | `Project_transition_settingsDBApi` - Project transition settings | ~277 | Yes |
+| `global_transition_defaults.ts` | `Global_transition_defaultsDBApi` - Global transition defaults | ~155 | Yes |
+| `global_ui_control_defaults.ts` | `Global_ui_control_defaultsDBApi` - Global UI control defaults | ~160 | Yes |
+| `project_ui_control_settings.ts` | `Project_ui_control_settingsDBApi` - Project UI control settings | ~150 | Yes |
+| `publish_events.ts` | `Publish_eventsDBApi` - Publishing history | 101 | Yes |
+| `pwa_caches.ts` | `Pwa_cachesDBApi` - PWA manifests | 76 | Yes |
+| `access_logs.ts` | `Access_logsDBApi` - Audit trail | 88 | Yes |
+| `presigned_url_requests.ts` | `Presigned_url_requestsDBApi` - S3 URL audit | 90 | Yes |
+| `file.ts` | `FileDBApi` - Polymorphic file attachments | ~95 | No (custom) |
+| `runtime-context.ts` | Runtime context helpers | 57 | - |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         DB API Layer Architecture                        │
+└─────────────────────────────────────────────────────────────────────────┘
+
+                        ┌─────────────────────┐
+                        │    Service Layer    │
+                        │  (services/*.js)    │
+                        └──────────┬──────────┘
+                                   │
+                                   ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           DB API Layer                                   │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                      GenericDBApi (base.api.ts)                 │    │
+│  │                                                                  │    │
+│  │  Static Getters (Configuration):                                 │    │
+│  │    • MODEL, TABLE_NAME                                           │    │
+│  │    • SEARCHABLE_FIELDS, RANGE_FIELDS, ENUM_FIELDS, UUID_FIELDS  │    │
+│  │    • ASSOCIATIONS, RELATION_FILTERS                              │    │
+│  │    • FIND_BY_INCLUDES, FIND_ALL_INCLUDES                        │    │
+│  │    • JSON_FIELDS, FIELD_DEFAULTS, FIELD_TRANSFORMERS            │    │
+│  │    • CSV_FIELDS, AUTOCOMPLETE_FIELD                             │    │
+│  │                                                                  │    │
+│  │  Methods (CRUD + Query):                                         │    │
+│  │    • create(), bulkImport(), update()                           │    │
+│  │    • deleteByIds(), remove()                                    │    │
+│  │    • findBy(), findAll(), findAllAutocomplete()                 │    │
+│  │    • getFieldMapping(), toCSV()                                 │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                   │                                      │
+│                    ┌──────────────┼──────────────┐                      │
+│                    │              │              │                      │
+│                    ▼              ▼              ▼                      │
+│  ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐        │
+│  │  Simple Entity   │ │ Runtime-Aware    │ │ Fully Custom     │        │
+│  │     API          │ │     API          │ │     API          │        │
+│  │                  │ │                  │ │                  │        │
+│  │ • PermissionsDB  │ │ • Tour_pagesDB   │ │ • UsersDBApi     │        │
+│  │ • RolesDBApi     │ │ • ProjectsDBApi  │ │ • FileDBApi      │        │
+│  │ • AssetsDBApi    │ │ • AudioTracksDB  │ │                  │        │
+│  │                  │ │                  │ │                  │        │
+│  │ Override only:   │ │ Override:        │ │ Fully custom     │        │
+│  │ - Static getters │ │ - Static getters │ │ implementation   │        │
+│  │ - getFieldMapping│ │ - findBy()       │ │                  │        │
+│  │                  │ │ - findAll()      │ │                  │        │
+│  └──────────────────┘ └──────────────────┘ └──────────────────┘        │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    Supporting Utilities                          │    │
+│  │    runtime-context.ts - Environment/project filtering helpers    │    │
+│  │    ../utils.js - UUID validation, ILIKE query building           │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+                                   │
+                                   ▼
+                        ┌─────────────────────┐
+                        │   Sequelize Models  │
+                        │  (models/*.js)      │
+                        └─────────────────────┘
+```
+
+---
+
+## GenericDBApi Base Class
+
+**Location:** `backend/src/db/api/base.api.ts`
+
+The base class provides a Template Method pattern where subclasses configure behavior through static getters and optionally override methods for custom logic.
+
+### Static Getters (Configuration)
+
+| Getter | Type | Default | Description |
+|--------|------|---------|-------------|
+| `MODEL` | Model | (required) | Sequelize model reference |
+| `TABLE_NAME` | string | From MODEL | Database table name |
+| `SEARCHABLE_FIELDS` | string[] | `[]` | Fields for ILIKE text search |
+| `RANGE_FIELDS` | string[] | `[]` | Fields for range queries (min/max) |
+| `ENUM_FIELDS` | string[] | `[]` | Fields for exact match filtering |
+| `UUID_FIELDS` | string[] | `[]` | UUID foreign key fields (validated before query) |
+| `RELATION_FILTERS` | object[] | `[]` | Related entity filter configs |
+| `ASSOCIATIONS` | object[] | `[]` | M:N or belongsTo setters |
+| `FIND_BY_INCLUDES` | object[] | `[]` | Includes for findBy() |
+| `FIND_ALL_INCLUDES` | object[] | `[]` | Includes for findAll() |
+| `CSV_FIELDS` | string[] | `['id', 'createdAt']` | Fields for CSV export |
+| `AUTOCOMPLETE_FIELD` | string | `'name'` | Field for autocomplete |
+| `JSON_FIELDS` | string[] | `[]` | Fields to auto-stringify |
+| `FIELD_DEFAULTS` | object | `{}` | Default values for fields |
+| `FIELD_TRANSFORMERS` | object | `{}` | Custom field transformations |
+
+### Methods
+
+#### getFieldMapping(data)
+
+Transforms input data for database operations using declarative configuration:
+
+```javascript
+static getFieldMapping(data) {
+  if (!data) return data;
+  const mapped = { ...data };
+
+  // 1. Apply field defaults
+  for (const [field, config] of Object.entries(this.FIELD_DEFAULTS)) {
+    if (mapped[field] === undefined) {
+      mapped[field] = config.default;
+    } else if (mapped[field] === null && config.nullDefault !== undefined) {
+      mapped[field] = config.nullDefault;
+    }
+  }
+
+  // 2. Auto-stringify JSON fields
+  for (const field of this.JSON_FIELDS) {
+    if (mapped[field] !== undefined && mapped[field] !== null) {
+      if (typeof mapped[field] !== 'string') {
+        mapped[field] = JSON.stringify(mapped[field]);
+      }
+    }
+  }
+
+  // 3. Apply custom transformers
+  for (const [field, transformer] of Object.entries(this.FIELD_TRANSFORMERS)) {
+    if (mapped[field] !== undefined) {
+      mapped[field] = transformer(mapped[field]);
+    }
+  }
+
+  return mapped;
+}
+```
+
+#### create(options)
+
+Creates a new record with associations:
+
+```javascript
+static async create({ data, currentUser = { id: null }, transaction, runtimeContext }) {
+
+  const mappedData = this.getFieldMapping(data);
+
+  const record = await this.MODEL.create(
+    {
+      ...mappedData,
+      importHash: data.importHash || null,
+      createdById: currentUser.id,
+      updatedById: currentUser.id,
+    },
+    { transaction },
+  );
+
+  // Handle M:N and belongsTo associations
+  for (const assoc of this.ASSOCIATIONS) {
+    if (data[assoc.field] !== undefined) {
+      const setter = record[assoc.setter];
+      await setter.call(
+        record,
+        data[assoc.field] || (assoc.isArray ? [] : null),
+        { transaction },
+      );
+    }
+  }
+
+  return record;
+}
+```
+
+#### update({ id, data, currentUser, transaction, runtimeContext })
+
+Updates a record with partial data:
+
+```javascript
+static async update({ id, data, currentUser = { id: null }, transaction }) {
+
+  const record = await this.MODEL.findByPk(id, { transaction });
+
+  if (!record) {
+    throw { status: 404, message: `${this.TABLE_NAME} not found` };
+  }
+
+  const updatePayload = { updatedById: currentUser.id };
+  const mappedData = this.getFieldMapping(data);
+
+  // Only update defined fields
+  for (const [key, value] of Object.entries(mappedData)) {
+    if (value !== undefined) {
+      updatePayload[key] = value;
+    }
+  }
+
+  await record.update(updatePayload, { transaction });
+
+  // Update associations
+  for (const assoc of this.ASSOCIATIONS) {
+    if (data[assoc.field] !== undefined) {
+      const setter = record[assoc.setter];
+      await setter.call(record, data[assoc.field], { transaction });
+    }
+  }
+
+  return record;
+}
+```
+
+#### findAll(filter, options)
+
+Full-featured query with filtering, pagination, and sorting:
+
+```javascript
+static async findAll(filter = {}, options = {}) {
+  const limit = filter.limit || 0;
+  const currentPage = +filter.page || 0;
+  const offset = currentPage * limit;
+
+  let where = {};
+  let include = [...this.FIND_ALL_INCLUDES];
+
+  // ID exact match (with UUID validation)
+  if (filter.id) {
+    if (!Utils.isValidUuid(filter.id)) {
+      return { rows: [], count: 0 };
+    }
+    where.id = filter.id;
+  }
+
+  // Text search (ILIKE)
+  for (const field of this.SEARCHABLE_FIELDS) {
+    if (filter[field]) {
+      where[Op.and] = Utils.ilike(this.TABLE_NAME, field, filter[field]);
+    }
+  }
+
+  // Range queries (fieldRange: [min, max])
+  for (const field of this.RANGE_FIELDS) {
+    const rangeKey = `${field}Range`;
+    if (filter[rangeKey]) {
+      const [start, end] = filter[rangeKey];
+      if (start) where[field] = { ...where[field], [Op.gte]: start };
+      if (end) where[field] = { ...where[field], [Op.lte]: end };
+    }
+  }
+
+  // Enum exact match
+  for (const field of this.ENUM_FIELDS) {
+    if (filter[field] !== undefined) {
+      where[field] = filter[field];
+    }
+  }
+
+  // Relation filters (search by related entity ID or name)
+  for (const rel of this.RELATION_FILTERS) {
+    if (filter[rel.filterKey]) {
+      // ... adds required include with where clause
+    }
+  }
+
+  // createdAt date range
+  if (filter.createdAtRange) {
+    // ... applies date range
+  }
+
+  const queryOptions = {
+    where,
+    include,
+    distinct: true,
+    order: filter.field && filter.sort
+      ? [[filter.field, filter.sort]]
+      : [['createdAt', 'desc']],
+    transaction: options.transaction,
+  };
+
+  if (!options.countOnly) {
+    queryOptions.limit = limit ? Number(limit) : undefined;
+    queryOptions.offset = offset ? Number(offset) : undefined;
+  }
+
+  const { rows, count } = await this.MODEL.findAndCountAll(queryOptions);
+  return { rows: options.countOnly ? [] : rows, count };
+}
+```
+
+#### Other Methods
+
+| Method | Description |
+|--------|-------------|
+| `bulkImport(data, options)` | Bulk create with timestamps offset |
+| `deleteByIds({ ids, currentUser, transaction, runtimeContext })` | Soft delete multiple records |
+| `remove({ id, currentUser, transaction, runtimeContext })` | Soft delete single record |
+| `findBy(where, options)` | Find single record by criteria |
+| `findAllAutocomplete({ query, limit, offset }, options)` | Autocomplete search |
+| `toCSV(rows)` | Convert rows to CSV string |
+
+---
+
+## Query Filter Patterns
+
+### SEARCHABLE_FIELDS - Text Search
+
+Case-insensitive partial match using ILIKE:
+
+```javascript
+// Configuration
+static get SEARCHABLE_FIELDS() {
+  return ['name', 'description', 'email'];
+}
+
+// Usage
+GET /api/users?name=john
+// Generates: WHERE LOWER(users.name) LIKE '%john%'
+```
+
+### RANGE_FIELDS - Range Queries
+
+Min/max range filtering:
+
+```javascript
+// Configuration
+static get RANGE_FIELDS() {
+  return ['sort_order', 'price', 'created_at'];
+}
+
+// Usage
+GET /api/assets?sort_orderRange=[0,10]
+// Generates: WHERE sort_order >= 0 AND sort_order <= 10
+
+GET /api/users?createdAtRange=[2024-01-01,2024-12-31]
+// Generates: WHERE createdAt >= '2024-01-01' AND createdAt <= '2024-12-31'
+```
+
+### ENUM_FIELDS - Exact Match
+
+Direct equality filtering:
+
+```javascript
+// Configuration
+static get ENUM_FIELDS() {
+  return ['environment', 'status', 'asset_type'];
+}
+
+// Usage
+GET /api/tour_pages?environment=production
+// Generates: WHERE environment = 'production'
+```
+
+### RELATION_FILTERS - Related Entity Search
+
+Filter by related entity ID or searchable field:
+
+```javascript
+// Configuration
+static get RELATION_FILTERS() {
+  return [
+    {
+      filterKey: 'project',      // Query param name
+      model: db.projects,        // Related model
+      as: 'project',             // Association alias
+      searchField: 'name',       // Field for text search
+    },
+  ];
+}
+
+// Usage
+GET /api/assets?project=abc123
+// Filters by project ID: abc123
+
+GET /api/assets?project=my-tour
+// Filters by project name containing "my-tour"
+
+GET /api/assets?project=abc123|my-tour
+// Pipe-separated: matches either
+```
+
+---
+
+## API Categories
+
+### 1. Simple Entity APIs
+
+Extend `GenericDBApi` with minimal configuration. Only override static getters and `getFieldMapping()`.
+
+**Example: PermissionsDBApi**
+
+```typescript
+class PermissionsDBApi extends GenericDBApi {
+  static override get MODEL(): unknown { return db.permissions; }
+  static override get TABLE_NAME(): string { return 'permissions'; }
+  static override get SEARCHABLE_FIELDS(): string[] { return ['name']; }
+  static override get CSV_FIELDS(): string[] { return ['id', 'name', 'createdAt']; }
+  static override get AUTOCOMPLETE_FIELD(): string { return 'name'; }
+
+  static override getFieldMapping(data: PermissionData): PermissionFieldMapping {
+    return {
+      id: data.id || undefined,
+      name: data.name || null,
+    };
+  }
+}
+```
+
+**Entities using this pattern:**
+- `PermissionsDBApi`
+- `AssetsDBApi`
+- `Asset_variantsDBApi`
+- `Publish_eventsDBApi`
+- `Pwa_cachesDBApi`
+- `Access_logsDBApi`
+- `Presigned_url_requestsDBApi`
+
+### 2. Runtime-Aware APIs
+
+Override `findBy()` and `findAll()` to apply runtime environment/project filters for public presentation access.
+
+**Example: Tour_pagesDBApi**
+
+```javascript
+class Tour_pagesDBApi extends GenericDBApi {
+  // ... configuration getters ...
+
+  static async findBy(where, options = {}) {
+    const queryWhere = applyRuntimeEnvironment({ ...where }, options);
+    const projectInclude = applyRuntimeProjectFilter(
+      { model: db.projects, as: 'project' },
+      options,
+    );
+
+    const record = await this.MODEL.findOne({
+      where: queryWhere,
+      include: [projectInclude],
+    });
+
+    return record ? record.get({ plain: true }) : null;
+  }
+
+  static async findAll(filter = {}, options = {}) {
+    // ... standard filtering logic ...
+
+    // Apply runtime environment filter
+    where = applyRuntimeEnvironment(where, options);
+
+    // Apply project slug filter to include
+    include[0] = applyRuntimeProjectFilter(include[0], options);
+
+    // ... execute query ...
+  }
+}
+```
+
+**Example: ProjectsDBApi**
+
+`ProjectsDBApi` uses runtime slug filtering but with two unique behaviors:
+
+1. **Auto-snapshot on create**: Copies global element defaults to new projects
+2. **Slug filter skipped for ID lookups**: Prevents stale `X-Runtime-Project-Slug` headers from breaking ID-based queries
+
+```javascript
+class ProjectsDBApi extends GenericDBApi {
+  // ... configuration getters ...
+
+  static async findBy(where, options = {}) {
+    const runtimeProjectSlug = getRuntimeProjectSlug(options);
+    const queryWhere = { ...where };
+
+    // Runtime access: filter by project slug
+    // Skip if finding by ID (unambiguous lookup)
+    if (runtimeProjectSlug && !where.id) {
+      queryWhere.slug = runtimeProjectSlug;
+    }
+
+    const record = await this.MODEL.findOne({
+      where: queryWhere,
+      include: options.include ?? this.DEFAULT_INCLUDES,
+    });
+
+    return record ? record.get({ plain: true }) : null;
+  }
+
+  static async create(options) {
+    const { transaction } = options;
+    // Create the project using parent's create
+    const project = await super.create(options);
+
+    // Auto-snapshot global element defaults to the new project
+    await Project_element_defaultsDBApi.snapshotGlobalDefaults(project.id, {
+      ...options,
+      transaction,
+    });
+
+    return project;
+  }
+
+  static async findAll(filter = {}, options = {}) {
+    // ... standard filtering logic ...
+
+    // Runtime access: filter by project slug (no ID bypass needed for list)
+    const runtimeProjectSlug = getRuntimeProjectSlug(options);
+    if (runtimeProjectSlug) {
+      where.slug = runtimeProjectSlug;
+    }
+
+    // ... execute query ...
+  }
+}
+```
+
+**Entities using this pattern:**
+- `Tour_pagesDBApi` - Environment filtering via `applyRuntimeEnvironment()`
+- `ProjectsDBApi` - Slug filtering with ID bypass and auto-snapshot on create
+- `Project_audio_tracksDBApi` - Environment filtering
+
+### 3. APIs with Custom Methods
+
+Extend base functionality with domain-specific methods.
+
+**Example: Element_type_defaultsDBApi**
+
+```javascript
+class Element_type_defaultsDBApi extends GenericDBApi {
+  // ... configuration ...
+
+  // Self-initialization pattern
+  static async ensureInitialized() {
+    if (!this.initializationPromise) {
+      this.initializationPromise = (async () => {
+        const count = await this.MODEL.count();
+        if (count > 0) return;
+
+        // Seed default rows
+        await this.MODEL.bulkCreate(
+          this.DEFAULT_ROWS.map((item) => this.getFieldMapping(item)),
+        );
+      })();
+    }
+    await this.initializationPromise;
+  }
+
+  // Override all methods to ensure initialization
+  static async create(options) {
+    await this.ensureInitialized();
+    return super.create(options);
+  }
+
+  // ... similar overrides for other methods ...
+
+  // Default data configuration
+  static get DEFAULT_ROWS() {
+    return [
+      { element_type: 'navigation_next', name: 'Navigation Forward Button', ... },
+      { element_type: 'tooltip', name: 'Tooltip', ... },
+      // ... 11 default element types
+    ];
+  }
+}
+```
+
+**Example: Project_element_defaultsDBApi**
+
+```javascript
+class Project_element_defaultsDBApi extends GenericDBApi {
+  // ... configuration ...
+
+  // Snapshot global defaults to a project
+  static async snapshotGlobalDefaults(projectId, options = {}) {
+    const globalDefaults = await Element_type_defaultsDBApi.findAll({});
+
+    return this.MODEL.bulkCreate(
+      globalDefaults.rows.map((global) => ({
+        projectId,
+        element_type: global.element_type,
+        settings_json: global.default_settings_json,
+        source_element_id: global.id,
+        snapshot_version: 1,
+      })),
+      { transaction: options.transaction },
+    );
+  }
+
+  // Reset project default to current global
+  static async resetToGlobal(id, options = {}) {
+    const projectDefault = await this.MODEL.findByPk(id);
+    const globalDefault = await Element_type_defaultsDBApi.MODEL.findOne({
+      where: { element_type: projectDefault.element_type },
+    });
+
+    await projectDefault.update({
+      settings_json: globalDefault.default_settings_json,
+      snapshot_version: projectDefault.snapshot_version + 1,
+    });
+
+    return projectDefault.reload();
+  }
+
+  // Compare project default with global
+  static async getDiffFromGlobal(id) {
+    // ... returns diff object
+  }
+}
+```
+
+### 4. Fully Custom APIs
+
+Don't extend `GenericDBApi` due to significantly different requirements.
+
+**Example: UsersDBApi**
+
+Complex user management with:
+- Password hashing (bcrypt)
+- File avatar handling
+- Token generation for email verification and password reset
+- OAuth authentication support
+
+```typescript
+class UsersDBApi {
+  static async create(options: UserCreateOptions): Promise<UserRecord> {
+    const { data, currentUser = { id: null }, transaction } = options;
+    const users = await db.users.create({
+      firstName: data.firstName || null,
+      lastName: data.lastName || null,
+      email: data.email || null,
+      password: data.password || null,  // Already hashed by service
+      // ...
+    }, { transaction });
+
+    // Auto-assign default role
+    if (!data.app_role) {
+      const role = await db.roles.findOne({ where: { name: 'User' } });
+      await users.setApp_role(role, { transaction });
+    }
+
+    // Handle avatar file
+    await FileDBApi.replaceRelationFiles(
+      { belongsTo: 'users', belongsToColumn: 'avatar', belongsToId: users.id },
+      data.data.avatar,
+      options,
+    );
+
+    return users;
+  }
+
+  static async update({ id, data, currentUser, transaction, runtimeContext }) {
+    const users = await db.users.findByPk(id, { transaction });
+
+    // Hash password if changed
+    if (data.password) {
+      data.password = bcrypt.hashSync(data.password, config.bcrypt.saltRounds);
+    } else {
+      data.password = users.password;
+    }
+
+    // ... update fields ...
+  }
+
+  // Token generation
+  static async generateEmailVerificationToken(email, options) {
+    return this._generateToken(
+      ['emailVerificationToken', 'emailVerificationTokenExpiresAt'],
+      email,
+      options,
+    );
+  }
+
+  static async _generateToken(keyNames, email, options) {
+    const users = await db.users.findOne({ where: { email: email.toLowerCase() } });
+    const token = crypto.randomBytes(20).toString('hex');
+    const tokenExpiresAt = Date.now() + (24 * 60 * 60 * 1000); // 24 hours
+
+    await users.update({
+      [keyNames[0]]: token,
+      [keyNames[1]]: tokenExpiresAt,
+    });
+
+    return token;
+  }
+
+  // Token lookup
+  static async findByPasswordResetToken(token, options) {
+    return db.users.findOne({
+      where: {
+        passwordResetToken: token,
+        passwordResetTokenExpiresAt: { [Op.gt]: Date.now() },
+      },
+    });
+  }
+};
+```
+
+**Example: FileDBApi**
+
+Polymorphic file attachment handling:
+
+```typescript
+export default class FileDBApi {
+  static async replaceRelationFiles(relation, rawFiles, options = {}) {
+    assert(relation.belongsTo);
+    assert(relation.belongsToColumn);
+    assert(relation.belongsToId);
+
+    const files = Array.isArray(rawFiles) ? rawFiles : rawFiles ? [rawFiles] : [];
+
+    await this._removeLegacyFiles(relation, files, options);
+    await this._addFiles(relation, files, options);
+  }
+
+  static async _addFiles(relation, files, options) {
+    const inexistentFiles = files.filter((file) => !!file.new);
+
+    for (const file of inexistentFiles) {
+      await db.file.create({
+        belongsTo: relation.belongsTo,
+        belongsToColumn: relation.belongsToColumn,
+        belongsToId: relation.belongsToId,
+        name: file.name,
+        publicUrl: file.publicUrl,
+        privateUrl: file.privateUrl,
+      }, { transaction: options.transaction });
+    }
+  }
+
+  static async _removeLegacyFiles(relation, files, options) {
+    const filesToDelete = await db.file.findAll({
+      where: {
+        belongsTo: relation.belongsTo,
+        belongsToId: relation.belongsToId,
+        belongsToColumn: relation.belongsToColumn,
+        id: { [Op.notIn]: files.filter((f) => !f.new).map((f) => f.id) },
+      },
+    });
+
+    for (const file of filesToDelete) {
+      await services.deleteFile(file.privateUrl);
+      await file.destroy({ transaction: options.transaction });
+    }
+  }
+};
+```
+
+---
+
+## Runtime Context Helpers
+
+**Location:** `backend/src/db/api/runtime-context.ts`
+
+Utilities for filtering queries based on runtime presentation context (public tour access).
+
+```javascript
+// Get runtime environment from options.runtimeContext
+function getRuntimeEnvironment(options = {}) {
+  const runtimeContext = options.runtimeContext || null;
+  if (!runtimeContext) return null;
+
+  // SECURITY: Only allow 'production' and 'stage' from header
+  if (runtimeContext.headerEnvironment === 'production') return 'production';
+  if (runtimeContext.headerEnvironment === 'stage') return 'stage';
+  return null;
+}
+
+// Get project slug from runtime context
+function getRuntimeProjectSlug(options = {}) {
+  const runtimeContext = options.runtimeContext || null;
+  return runtimeContext?.headerProjectSlug || null;
+}
+
+// Apply environment filter to where clause
+function applyRuntimeEnvironment(where = {}, options = {}) {
+  const environment = getRuntimeEnvironment(options);
+  if (!environment) return where;
+
+  return { ...where, environment };
+}
+
+// Apply project slug filter to include
+function applyRuntimeProjectFilter(projectInclude = {}, options = {}) {
+  const projectSlug = getRuntimeProjectSlug(options);
+  if (!projectSlug) return projectInclude;
+
+  return {
+    ...projectInclude,
+    required: true,
+    where: { ...(projectInclude.where || {}), slug: projectSlug },
+  };
+}
+```
+
+**Usage:**
+
+```javascript
+// In runtime-aware API
+static async findAll(filter = {}, options = {}) {
+  let where = { /* ... */ };
+  let include = [{ model: db.projects, as: 'project' }];
+
+  // Apply runtime filters
+  where = applyRuntimeEnvironment(where, options);
+  include[0] = applyRuntimeProjectFilter(include[0], options);
+
+  // ... execute query
+}
+```
+
+---
+
+## DB Utils
+
+**Location:** `backend/src/db/utils.js`
+
+Utility functions for UUID validation and query building:
+
+```javascript
+const validator = require('validator');
+const { v4: uuidv4 } = require('uuid');
+
+module.exports = class Utils {
+  // Check if value is a valid UUID
+  static isValidUuid(value) {
+    return Boolean(value && validator.isUUID(String(value)));
+  }
+
+  // Generate a new UUID v4
+  static generateUuid() {
+    return uuidv4();
+  }
+
+  // Filter array to only valid UUIDs
+  static filterValidUuids(values) {
+    return values.filter((v) => this.isValidUuid(v));
+  }
+
+  // Case-insensitive LIKE query
+  static ilike(model, column, value) {
+    return Sequelize.where(
+      Sequelize.fn('lower', Sequelize.col(`${model}.${column}`)),
+      { [Sequelize.Op.like]: `%${value}%`.toLowerCase() },
+    );
+  }
+};
+```
+
+**UUID Utility Functions:**
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `isValidUuid(value)` | Check if valid UUID | `boolean` |
+| `generateUuid()` | Create new UUID v4 | `string` |
+| `filterValidUuids(values)` | Filter array to valid UUIDs only | `string[]` |
+| `ilike(model, column, value)` | Case-insensitive search | Sequelize where clause |
+
+**UUID Validation Behavior:**
+- Invalid single ID filter (`?id=xxx`) → returns `{ rows: [], count: 0 }` immediately
+- Invalid UUID in relation filter (`?project=uuid|name`) → filters out invalid UUIDs for ID search, keeps all terms for text search
+- Invalid UUID field filter (`?projectId=xxx`) → returns `{ rows: [], count: 0 }` immediately
+
+---
+
+## Declarative Configuration Examples
+
+### Simple Entity
+
+```javascript
+class AssetsDBApi extends GenericDBApi {
+  static get MODEL() { return db.assets; }
+  static get TABLE_NAME() { return 'assets'; }
+
+  static get SEARCHABLE_FIELDS() {
+    return ['name', 'cdn_url', 'storage_key', 'mime_type', 'checksum'];
+  }
+
+  static get RANGE_FIELDS() {
+    return ['size_mb', 'width_px', 'height_px', 'duration_sec'];
+  }
+
+  static get ENUM_FIELDS() {
+    return ['asset_type', 'type', 'is_public'];
+  }
+
+  // UUID foreign key fields - validated before querying
+  static get UUID_FIELDS() {
+    return ['projectId'];
+  }
+
+  static get ASSOCIATIONS() {
+    return [{ field: 'project', setter: 'setProject', isArray: false }];
+  }
+
+  static get FIND_BY_INCLUDES() {
+    return [
+      { association: 'asset_variants_asset' },
+      { association: 'project' },
+    ];
+  }
+
+  static get RELATION_FILTERS() {
+    return [
+      { filterKey: 'project', model: db.projects, as: 'project', searchField: 'name' },
+    ];
+  }
+
+  static getFieldMapping(data) {
+    return {
+      name: data.name || null,
+      asset_type: data.asset_type || null,
+      type: data.type || 'general',
+      cdn_url: data.cdn_url || null,
+      storage_key: data.storage_key || null,
+      mime_type: data.mime_type || null,
+      size_mb: data.size_mb || null,
+      width_px: data.width_px || null,
+      height_px: data.height_px || null,
+      duration_sec: data.duration_sec || null,
+      checksum: data.checksum || null,
+      is_public: data.is_public || false,
+    };
+  }
+}
+```
+
+### Foreign Key Fields in getFieldMapping
+
+**Important:** Foreign key fields (like `assetId`, `projectId`) must be included in `getFieldMapping()` if they are passed directly to `create()` or `update()`. Without this, the foreign key value is silently dropped and the record is created without the relationship.
+
+**Two ways to handle foreign keys:**
+
+1. **Direct field mapping** (preferred for programmatic use):
+```javascript
+// In getFieldMapping()
+static getFieldMapping(data) {
+  return {
+    assetId: data.assetId || null,  // Include FK field directly
+    variant_type: data.variant_type || null,
+    // ...
+  };
+}
+
+// In service
+await Asset_variantsDBApi.create({ assetId: asset.id, ... });
+```
+
+2. **Via ASSOCIATIONS setter** (used by frontend forms):
+```javascript
+// ASSOCIATIONS config uses 'asset' (relation name)
+static get ASSOCIATIONS() {
+  return [{ field: 'asset', setter: 'setAsset', isArray: false }];
+}
+
+// Service passes 'asset' instead of 'assetId'
+await Asset_variantsDBApi.create({ asset: asset.id, ... });
+// GenericDBApi.create() calls record.setAsset(asset.id) with record as `this`
+```
+
+**Common mistake:** Passing `assetId` when only `asset` association is configured (or vice versa) results in orphaned records with NULL foreign keys.
+
+**Implementation detail:** Sequelize association mixins rely on the model
+instance as `this`. `GenericDBApi` must call association setters as bound
+record methods (`setter.call(record, ...)`) rather than detached functions;
+otherwise belongsTo setters such as `setProject`/`setAsset` receive an
+undefined source instance and fail before the foreign key can be saved.
+
+### Entity with M:N Relations
+
+```typescript
+class RolesDBApi extends GenericDBApi {
+  static override get MODEL(): unknown { return db.roles; }
+
+  static override get ASSOCIATIONS(): RoleAssociationConfig[] {
+    return [{ field: 'permissions', setter: 'setPermissions', isArray: true }];
+  }
+
+  static override get FIND_BY_INCLUDES(): unknown[] {
+    return [
+      { association: 'users_app_role' },
+      { association: 'permissions' },
+    ];
+  }
+
+  static override get FIND_ALL_INCLUDES(): unknown[] {
+    return [
+      { model: db.permissions, as: 'permissions', required: false },
+    ];
+  }
+
+  static get RELATION_FILTERS() {
+    return [
+      { filterKey: 'permissions', model: db.permissions, as: 'permissions_filter', searchField: 'name' },
+    ];
+  }
+}
+```
+
+### Entity with JSON Fields and Defaults
+
+```javascript
+class Element_type_defaultsDBApi extends GenericDBApi {
+  // Auto-stringify JSON fields
+  static get JSON_FIELDS() {
+    return ['default_settings_json'];
+  }
+
+  // Field defaults
+  static get FIELD_DEFAULTS() {
+    return {
+      element_type: { default: null },
+      name: { default: null },
+      sort_order: { default: 0 },
+    };
+  }
+
+  static getFieldMapping(data) {
+    // Apply base class transformations first
+    const mapped = super.getFieldMapping(data);
+
+    return {
+      id: mapped.id || undefined,
+      element_type: mapped.element_type,
+      name: mapped.name,
+      sort_order: mapped.sort_order,
+      default_settings_json: mapped.default_settings_json,
+    };
+  }
+}
+```
+
+---
+
+## API Summary Table
+
+| API | Pattern | Getters | Custom Methods | Notes |
+|-----|---------|---------|----------------|-------|
+| `PermissionsDBApi` | Simple | 6 | 0 | Minimal config |
+| `AssetsDBApi` | Simple | 9 | 0 | With associations |
+| `RolesDBApi` | Simple | 10 | 0 | M:N permissions |
+| `ProjectsDBApi` | Runtime-aware | 10 | 3 | Auto-snapshot on create, slug filter skipped for ID lookups |
+| `Tour_pagesDBApi` | Runtime-aware | 9 | 0 | Environment filtering |
+| `Project_audio_tracksDBApi` | Runtime-aware | 8 | 0 | Environment filtering |
+| `Element_type_defaultsDBApi` | Self-init | 9 | 1 | Default seeding |
+| `Project_element_defaultsDBApi` | Extended | 10 | 4 | Snapshot, reset, diff |
+| `UsersDBApi` | Fully custom | - | 12 | Auth, tokens, files |
+| `FileDBApi` | Fully custom | - | 3 | Polymorphic files |
+
+---
+
+## Best Practices
+
+### When to Extend GenericDBApi
+
+- Standard CRUD operations needed
+- Filtering by searchable/range/enum fields
+- Pagination and sorting
+- CSV export
+- Autocomplete
+
+### When to Override Methods
+
+- Custom runtime environment filtering
+- Special business logic during create/update
+- Complex association handling
+- Self-initialization patterns
+
+### When to Use Fully Custom API
+
+- Complex authentication logic (password hashing, tokens)
+- Polymorphic associations (FileDBApi)
+- Significantly different query patterns
+- Multiple specialized methods
+
+---
+
+## Related Documentation
+
+- [DB Models Module](./db-models.md) - Sequelize model definitions
+- [Factories Module](./factories.md) - Service/router factories that use APIs
+- [Services Module](./services.md) - Business logic layer
+- [Middleware Module](./middleware.md) - Runtime context middleware
diff --git a/backend/docs/modules/db-config.md b/backend/docs/modules/db-config.md
new file mode 100644
index 0000000..bad02bf
--- /dev/null
+++ b/backend/docs/modules/db-config.md
@@ -0,0 +1,505 @@
+# DB Config Module
+
+## Overview
+
+The DB Config module manages database connection settings, environment validation, and database utilities. It provides environment-aware configuration for PostgreSQL connections via Sequelize ORM.
+
+**Location:** `backend/src/db/`
+
+**Key Files:**
+- `db-config.ts` - Typed ESM database connection settings per environment
+- `umzug.ts` - Typed Umzug runner for migrations, seeders, create/drop
+- `utils.ts` - Database utility functions
+- `sync.ts` - Development database sync script
+- `reset.ts` - Database reset script
+
+**Related Files:**
+- `backend/src/config.ts` - Application configuration
+- `backend/src/utils/env-validation.ts` - Environment variable validation
+
+---
+
+## Architecture
+
+```
+backend/
+├── src/
+│   ├── config.ts                     # Application config
+│   ├── utils/
+│   │   └── env-validation.ts         # Joi schema validation
+│   └── db/
+│       ├── db-config.ts              # Typed database connection config
+│       ├── umzug.ts                  # Typed migration/seed runner
+│       ├── utils.ts                  # DB utilities
+│       ├── sync.ts                   # Dev sync script (21 LOC)
+│       ├── reset.ts                  # Reset script (18 LOC)
+│       ├── models/
+│       │   ├── loader.ts             # Typed model loader + Sequelize init
+│       │   └── index.ts              # ESM model registry entrypoint
+│       ├── migrations/               # Schema migrations
+│       └── seeders/                  # Data seeders
+```
+
+---
+
+## Database Configuration
+
+### db-config.ts
+
+`db-config.ts` exports environment-specific database settings for Sequelize.
+It uses the official Sequelize `Options` type plus project-specific
+`DatabaseConfigMap`/`DatabaseEnvironmentConfig` reusable contracts from
+`backend/src/types/db-config.ts`.
+
+Database scripts use `backend/src/db/umzug.ts` directly.
+
+`DB_PORT` is parsed to a number for the Sequelize `Options` contract. If the
+env var is absent or invalid, the `port` property is omitted.
+
+### Environment Comparison
+
+| Setting | Production | Development | Dev Stage |
+|---------|------------|-------------|-----------|
+| **Dialect** | postgres | postgres | postgres |
+| **Credentials** | Env vars | Hardcoded | Env vars |
+| **Logging** | Disabled | Pino debug | Pino debug |
+| **Host** | Env var | localhost | Env var |
+| **Migration Storage** | SequelizeMeta | SequelizeMeta | SequelizeMeta |
+| **Seeder Storage** | SequelizeData | SequelizeData | SequelizeData |
+
+---
+
+## Environment Variables
+
+### Database Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NODE_ENV` | No | development | Environment selection |
+| `DB_HOST` | Prod/Stage | localhost | Database host |
+| `DB_PORT` | Prod/Stage | 5432 | Database port |
+| `DB_NAME` | Prod/Stage | db_tour_builder_platform | Database name |
+| `DB_USER` | Prod/Stage | postgres | Database username |
+| `DB_PASS` | Prod/Stage | (empty) | Database password |
+
+### Environment Validation
+
+The `env-validation.ts` file uses Joi schema to validate all environment variables:
+
+```javascript
+const Joi = require('joi');
+
+const envSchema = Joi.object({
+  NODE_ENV: Joi.string()
+    .valid('development', 'test', 'production', 'dev_stage')
+    .default('development'),
+
+  PORT: Joi.number().default(8080),
+
+  DB_HOST: Joi.string().default('localhost'),
+  DB_PORT: Joi.number().default(5432),
+  DB_NAME: Joi.string().default('db_tour_builder_platform'),
+  DB_USER: Joi.string().default('postgres'),
+  DB_PASS: Joi.string().allow('').default(''),
+
+  SECRET_KEY: Joi.string()
+    .min(16)
+    .default('88dbeaf8-e906-405e-9e41-c3baadeda5c6'),
+
+  // ... more variables
+}).unknown(true);
+```
+
+### Complete Environment Variable Schema
+
+| Category | Variable | Validation | Default |
+|----------|----------|------------|---------|
+| **Server** | NODE_ENV | enum: development, test, production, dev_stage | development |
+| | PORT | number | 8080 |
+| **Database** | DB_HOST | string | localhost |
+| | DB_PORT | number | 5432 |
+| | DB_NAME | string | db_tour_builder_platform |
+| | DB_USER | string | postgres |
+| | DB_PASS | string (allow empty) | (empty) |
+| **Auth** | SECRET_KEY | string, min 16 chars | (default UUID) |
+| | ADMIN_PASS | string | 88dbeaf8 |
+| | USER_PASS | string | c3baadeda5c6 |
+| | ADMIN_EMAIL | email | admin@flatlogic.com |
+| **OAuth** | GOOGLE_CLIENT_ID | string (allow empty) | (empty) |
+| | GOOGLE_CLIENT_SECRET | string (allow empty) | (empty) |
+| | MS_CLIENT_ID | string (allow empty) | (empty) |
+| | MS_CLIENT_SECRET | string (allow empty) | (empty) |
+| **AWS S3** | AWS_ACCESS_KEY_ID | string (allow empty) | (empty) |
+| | AWS_SECRET_ACCESS_KEY | string (allow empty) | (empty) |
+| | AWS_S3_BUCKET | string (allow empty) | (empty) |
+| | AWS_S3_REGION | string | us-east-1 |
+| | AWS_S3_PREFIX | string | (default hash) |
+| | AWS_S3_CONNECTION_TIMEOUT | number (ms) | 5000 |
+| | AWS_S3_REQUEST_TIMEOUT | number (ms) | 30000 |
+| | AWS_S3_MAX_ATTEMPTS | number | 3 |
+| | AWS_S3_MAX_SOCKETS | number | 50 |
+| | AWS_S3_KEEP_ALIVE | boolean string | true |
+| | AWS_S3_PRESIGN_EXPIRY | number (seconds) | 3600 |
+| **Email** | EMAIL_USER | string (allow empty) | (empty) |
+| | EMAIL_PASS | string (allow empty) | (empty) |
+| | EMAIL_TLS_REJECT_UNAUTHORIZED | enum: true, false | true |
+| **External APIs** | PEXELS_KEY | string (allow empty) | (empty) |
+| **Logging** | LOG_LEVEL | enum: fatal, error, warn, info, debug, trace | info |
+
+### Validation Behavior
+
+```javascript
+function validateEnv() {
+  const { error, value } = envSchema.validate(process.env, {
+    abortEarly: false,      // Report all errors, not just first
+    stripUnknown: false,    // Keep unknown env vars
+  });
+
+  if (error) {
+    const messages = error.details.map((d) => `  - ${d.message}`);
+    logger.error({ errors: messages }, 'Environment validation failed');
+
+    if (process.env.NODE_ENV === 'production') {
+      process.exit(1);  // Fatal in production
+    } else {
+      logger.warn('Continuing with default values in non-production mode');
+    }
+  }
+
+  return value;
+}
+```
+
+---
+
+## Umzug Configuration
+
+The database command entrypoint is `backend/src/db/umzug.ts`.
+
+### Runtime Paths
+
+| Setting | Path |
+|---------|------|
+| Config | `src/db/db-config.ts` |
+| Runner | `src/db/umzug.ts` |
+| Models | `src/db/models/` |
+| Seeders | `src/db/seeders/` |
+| Migrations | `src/db/migrations/` |
+
+---
+
+## Database Initialization
+
+### Model Loader
+
+`src/db/models/loader.ts` explicitly imports model factories and builds the
+Sequelize registry. `src/db/models/index.ts` is the ESM entrypoint. The typed
+service-specific overload facade lives in `src/types/db-models.ts`.
+
+### Initialization Flow
+
+```
+Server Start
+    │
+    ▼
+config.ts loads
+    │
+    ├─ dotenv.config()  ─── Load .env file
+    │
+    ├─ validateEnv()    ─── Validate with Joi schema
+    │                        │
+    │                        ├─ Production: Exit on error
+    │                        └─ Development: Warn, use defaults
+    │
+    └─ Export config object
+    │
+    ▼
+db/models/index.ts loads
+    │
+    ├─ Read NODE_ENV
+    │
+    ├─ Load db-config.ts[env]
+    │
+    ├─ Create Sequelize instance
+    │
+    ├─ Initialize explicitly imported model factories
+    │
+    ├─ Call model.associate() for relationships
+    │
+    └─ Export db object { sequelize, Sequelize, models... }
+```
+
+---
+
+## Database Utilities
+
+### utils.ts
+
+Database utility helpers are TypeScript/ESM source. Runtime DB access goes
+through `src/db/models/index.ts`, whose typed facade is provided by
+`src/types/db-models.ts`.
+
+### Usage Examples
+
+```typescript
+import Utils from '../db/utils.ts';
+
+// UUID validation
+Utils.isValidUuid('550e8400-e29b-41d4-a716-446655440000');  // true
+Utils.isValidUuid('not-a-uuid');                             // false
+
+// Generate new UUID
+const id = Utils.generateUuid();  // Returns new UUID v4
+
+// Filter array to valid UUIDs only
+const validIds = Utils.filterValidUuids(['uuid1', 'invalid', 'uuid2']);
+
+// Case-insensitive search
+const where = {
+  [Op.or]: [
+    Utils.ilike('users', 'firstName', searchTerm),
+    Utils.ilike('users', 'lastName', searchTerm),
+    Utils.ilike('users', 'email', searchTerm),
+  ]
+};
+```
+
+---
+
+## Database Scripts
+
+### sync.ts (Development Only)
+
+Synchronizes models to database schema using Sequelize's `alter` mode.
+
+```javascript
+async function syncDatabase() {
+  // Safety check - never run in production
+  if (process.env.NODE_ENV === 'production') {
+    console.error('ERROR: sync.ts should not be run in production. Use migrations instead.');
+    process.exit(1);
+  }
+
+  try {
+    console.log('Syncing database...');
+    await db.sequelize.sync({ alter: true });
+    console.log('Database synced successfully!');
+    process.exit(0);
+  } catch (error) {
+    console.error('Error syncing database:', error);
+    process.exit(1);
+  }
+}
+```
+
+**Usage:**
+```bash
+node src/db/sync.ts
+```
+
+**Sync Modes:**
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `{ force: true }` | Drop and recreate all tables | Fresh start |
+| `{ alter: true }` | Modify tables to match models | Development |
+| (none) | Create only missing tables | Safe default |
+
+### reset.ts
+
+Forcefully resets database and runs seeders.
+
+```javascript
+db.sequelize
+  .sync({ force: true })
+  .then(() => {
+    execSync('sequelize db:seed:all');
+    console.log('OK');
+    process.exit();
+  })
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+```
+
+**Usage:**
+```bash
+node src/db/reset.ts
+```
+
+**Warning:** This drops ALL tables and recreates them. Data loss!
+
+---
+
+## Application Configuration
+
+### config.ts
+
+Centralized application configuration with environment-aware settings.
+
+```javascript
+const env = validateEnv();
+
+const config = {
+  gcloud: {
+    bucket: 'fldemo-files',
+    hash: 'afeefb9d49f5b7977577876b99532ac7',
+    projectId: env.GC_PROJECT_ID,
+    clientEmail: env.GC_CLIENT_EMAIL,
+    privateKey: env.GC_PRIVATE_KEY,
+  },
+  fileStorage: {
+    provider: env.FILE_STORAGE_PROVIDER,
+  },
+  s3: {
+    bucket: env.AWS_S3_BUCKET,
+    region: env.AWS_S3_REGION,
+    accessKeyId: env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+    prefix: env.AWS_S3_PREFIX,
+    connectionTimeout: env.AWS_S3_CONNECTION_TIMEOUT,
+    requestTimeout: env.AWS_S3_REQUEST_TIMEOUT,
+    maxAttempts: env.AWS_S3_MAX_ATTEMPTS,
+    maxSockets: env.AWS_S3_MAX_SOCKETS,
+    keepAlive: env.AWS_S3_KEEP_ALIVE !== 'false',
+    presignExpirySeconds: env.AWS_S3_PRESIGN_EXPIRY,
+  },
+  resilience: {
+    ffmpeg: { reverseTimeoutMs, ffprobeTimeoutMs, breaker },
+    fileStorage: { breaker },
+  },
+  server: {
+    env: env.NODE_ENV,
+    port: serverPort,
+    swaggerServerUrl,
+  },
+  secret_key: env.SECRET_KEY,
+  admin_pass: env.ADMIN_PASS,
+  user_pass: env.USER_PASS,
+  admin_email: env.ADMIN_EMAIL,
+
+  // Roles
+  roles: {
+    admin: 'Administrator',
+    user: 'Analytics Viewer',
+  },
+  apiUrl: `${host}${port ? `:${port}` : ''}/api`,
+  swaggerUrl: `${swaggerUI}${swaggerPort}`,
+  uiUrl: `${hostUI}${portUI ? `:${portUI}` : ''}/#`,
+  backUrl: `${hostUI}${portUI ? `:${portUI}` : ''}`,
+};
+```
+
+---
+
+## Configuration Categories
+
+### Storage Configuration
+
+| Provider | Variables | Purpose |
+|----------|-----------|---------|
+| **AWS S3** | AWS_S3_BUCKET, AWS_S3_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY | File storage |
+| **GCloud** | (hardcoded bucket) | Legacy support |
+| **Local** | uploadDir (os.tmpdir()) | Development fallback |
+
+### S3 Performance Tuning
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| AWS_S3_CONNECTION_TIMEOUT | 5000ms | TCP connection timeout |
+| AWS_S3_REQUEST_TIMEOUT | 30000ms | Total request timeout |
+| AWS_S3_MAX_ATTEMPTS | 3 | Retry attempts on failure |
+| AWS_S3_MAX_SOCKETS | 50 | Connection pool size |
+| AWS_S3_KEEP_ALIVE | true | Reuse TCP connections |
+| AWS_S3_PRESIGN_EXPIRY | 3600s | Presigned URL validity (1 hour) |
+
+### Security Configuration
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| bcrypt.saltRounds | 12 | Password hashing strength |
+| SECRET_KEY | 16+ char string | JWT signing key |
+| EMAIL_TLS_REJECT_UNAUTHORIZED | true/false | TLS certificate validation |
+
+### URL Configuration
+
+| URL | Development | Production |
+|-----|-------------|------------|
+| apiUrl | http://localhost:3000/api | (remote)/api |
+| swaggerUrl | http://localhost:3000 | (remote) |
+| uiUrl | http://localhost:3001/# | (remote)/# |
+| backUrl | http://localhost:3001 | (remote) |
+
+---
+
+## Running Commands
+
+### Development
+```bash
+cd backend
+npm run start-dev
+```
+
+`start-dev` runs the standard `start` pipeline (`db:migrate`, `db:seed`,
+`watch`) with `LOG_PRETTY=true`. `src/load-env.ts` loads `backend/.env` before
+DB config selection; when `NODE_ENV` is absent it defaults to `dev_stage`, which
+matches the standard VM backend flow and listens on port `3000`.
+
+### VM / Dev Stage
+```bash
+cd backend
+npm run start
+```
+
+In the standard VM PM2 setup, `NODE_ENV=dev_stage` makes the backend listen on
+port `3000`; the frontend runs separately on `3001` and Apache proxies public
+traffic from port `80`. See [`deployment-vm.md`](../../../documentation/deployment-vm.md).
+
+Do not add `NODE_ENV=production` only to make local startup work. The current
+flow loads `.env` through `src/load-env.ts` and defaults missing `NODE_ENV` to
+`dev_stage`, matching the VM backend process.
+
+---
+
+## Best Practices
+
+### 1. Never Commit Secrets
+```bash
+# .env file should be in .gitignore
+# Use environment variables in deployment
+```
+
+### 2. Use Migrations in Production
+```javascript
+// Never use sync.ts or reset.ts in production
+if (process.env.NODE_ENV === 'production') {
+  process.exit(1);
+}
+```
+
+### 3. Validate Environment Early
+```javascript
+// config.ts loads validation at import time
+import { validateEnv } from './utils/env-validation.ts';
+validateEnv();  // Called before app starts
+```
+
+### 4. Environment-Specific Logging
+```javascript
+// Production: logging disabled (performance)
+// Development/dev_stage: SQL logs use structured Pino debug entries
+logging: process.env.NODE_ENV === 'production'
+  ? false
+  : (sql) => logger.debug({ sql }, 'Sequelize query'),
+```
+
+---
+
+## Related Documentation
+
+- [DB Models](./db-models.md) - Sequelize model definitions
+- [DB API](./db-api.md) - Database access layer
+- [DB Migrations](./db-migrations.md) - Schema evolution
+- [DB Seeders](./db-seeders.md) - Initial data population
+- [Core Module](./core.md) - Application entry point
diff --git a/backend/docs/modules/db-migrations.md b/backend/docs/modules/db-migrations.md
new file mode 100644
index 0000000..e023a3e
--- /dev/null
+++ b/backend/docs/modules/db-migrations.md
@@ -0,0 +1,764 @@
+# DB Migrations Module
+
+## Overview
+
+The DB Migrations module manages database schema evolution using a typed
+**Umzug v3** runner. It provides version-controlled, reversible database
+changes that run automatically on server startup.
+
+**Location:** `backend/src/db/migrations/`
+
+**Files:** 34+ migration files (as of June 2026)
+
+**Migration safety policy:** Do not rewrite, rename, or reformat already
+applied migration files. Production databases track migration names in
+`SequelizeMeta`, and fresh databases must replay the same schema history.
+
+---
+
+## Architecture
+
+```
+backend/
+├── package.json                    # Umzug-backed migration scripts
+└── src/db/
+    ├── db-config.ts               # Database connection settings
+    ├── umzug.ts                   # Typed Umzug runner
+    └── migrations/                 # Migration files
+        ├── package.json            # CommonJS boundary for legacy migrations
+        ├── 20260319000001-*.js    # Foreign key constraints
+        ├── 20260319000002-*.js    # Column cleanup
+        ├── 20260326000001-*.js    # Table rename
+        ├── 20260326000002-*.js    # ENUM to TEXT conversion
+        ├── 20260326000003-*.js    # Create table
+        ├── 20260326000004-*.js    # Data backfill
+        ├── 20260326000005-*.js    # Environment fix
+        ├── 20260326000006-*.js    # Cross-environment copy
+        ├── 20260326043002-*.js    # NOT NULL enforcement
+        ├── 20260326050442-*.js    # Column removal
+        ├── 20260326054410-*.js    # Column removal
+        ├── 20260326060000-*.js    # JSON data transformation
+        ├── 20260326060001-*.js    # Table drop (page_elements)
+        ├── 20260326060002-*.js    # Table drop (page_links)
+        ├── 20260326060003-*.js    # Table drop (transitions)
+        ├── 20260326171017-*.js    # Missing data insertion
+        ├── 20260327000001-*.js    # Full data sync
+        ├── 20260331024423-*.js    # Column removal (theme/css)
+        ├── 20260331054340-*.js    # Duplicate cleanup
+        ├── 20260331063424-*.js    # Invalid data cleanup
+        ├── 20260403000001-*.js    # Background video settings
+        ├── 20260409000001-*.js    # Design dimensions (projects)
+        ├── 20260409111309-*.js    # Design dimensions (tour_pages)
+        ├── 20260605000001-*.js    # Background audio settings
+        ├── 20260626000001-*.js    # Private production presentation access
+        ├── 20260626000002-*.js    # Account manager user creation permission
+        ├── 20260628000001-*.js    # Global UI-control settings tables
+        └── 20260628000005-*.js    # Existing-project UI-control snapshots
+```
+
+---
+
+## Configuration
+
+### Umzug Runner
+
+`backend/src/db/umzug.ts` owns migration and seeder execution. It uses official
+Umzug types, `SequelizeStorage`, and the existing storage tables:
+
+| Flow | Files | Storage Table | Stored Names |
+|------|-------|---------------|--------------|
+| Migrations | `src/db/migrations/*.js` | `SequelizeMeta` | `*.js` |
+| Seeders | `src/db/seeders/*.ts` in source, `dist/src/db/seeders/*.js` in build | `SequelizeData` | stable `*.js` names |
+
+Seeder files are typed ESM source, and the runner stores stable execution names
+so already executed seeders are not treated as pending.
+
+### NPM Scripts
+```bash
+# Run pending migrations
+npm run db:migrate
+
+# Undo last migration
+npm run db:migrate:undo
+
+# Undo all migrations
+npm run db:migrate:undo:all
+
+# Check migration status
+npm run db:migrate:status
+
+# Full database reset (drop, create, migrate, seed)
+npm run db:reset
+
+# Seed data
+npm run db:seed
+```
+
+---
+
+## Migration File Structure
+
+### Standard Template
+```javascript
+'use strict';
+
+/**
+ * Migration: [Description]
+ *
+ * [Explanation of what this migration does and why]
+ */
+module.exports = {
+  async up(queryInterface, Sequelize) {
+    // Apply changes
+  },
+
+  async down(queryInterface, Sequelize) {
+    // Revert changes
+  },
+};
+```
+
+Use one project-wide migration template for new schema changes. Do not modify
+already applied migration files to match newer style choices.
+
+### Naming Convention
+```
+YYYYMMDDHHMMSS-descriptive-name.js
+
+Examples:
+- 20260319000001-add-foreign-key-constraints.js
+- 20260326060000-convert-targetpageid-to-slug.js
+- 20260326060001-drop-page-elements-table.js
+- 20260628000001-create-ui-control-settings.js
+- 20260628000005-snapshot-existing-project-ui-controls.js
+```
+
+---
+
+## Migration Patterns
+
+### 1. Transaction Wrapper Pattern
+**Purpose:** Ensure atomic operations - all changes succeed or all fail.
+
+```javascript
+module.exports = {
+  async up(queryInterface) {
+    const transaction = await queryInterface.sequelize.transaction();
+
+    try {
+      // Multiple operations...
+      await queryInterface.addColumn('table', 'column', { ... }, { transaction });
+      await queryInterface.addIndex('table', ['column'], { transaction });
+
+      await transaction.commit();
+    } catch (error) {
+      await transaction.rollback();
+      throw error;
+    }
+  },
+};
+```
+
+**Used in:** Foreign key constraints, ENUM conversions, data transformations
+
+---
+
+### 2. Idempotent Check Pattern
+**Purpose:** Safely re-run migrations without errors.
+
+```javascript
+// Check if table/column/constraint exists before modifying
+const [results] = await queryInterface.sequelize.query(
+  `SELECT column_name FROM information_schema.columns
+   WHERE table_name = 'tableName' AND column_name = 'columnName'`,
+  { transaction }
+);
+
+if (results.length > 0) {
+  console.log('Column already exists, skipping');
+  return;
+}
+
+// Proceed with modification
+await queryInterface.addColumn('tableName', 'columnName', { ... });
+```
+
+**Used in:** All migrations that add columns, constraints, or tables
+
+---
+
+### 3. Helper Function Pattern
+**Purpose:** Reduce repetition for bulk operations.
+
+```javascript
+module.exports = {
+  async up(queryInterface) {
+    const transaction = await queryInterface.sequelize.transaction();
+
+    // Define reusable helper
+    const addForeignKey = async (tableName, columnName, references, onDelete) => {
+      const constraintName = `${tableName}_${columnName}_fkey`;
+
+      // Check existence
+      const [results] = await queryInterface.sequelize.query(
+        `SELECT constraint_name FROM information_schema.table_constraints
+         WHERE table_name = '${tableName}' AND constraint_name = '${constraintName}'`,
+        { transaction }
+      );
+
+      if (results.length === 0) {
+        await queryInterface.addConstraint(tableName, {
+          fields: [columnName],
+          type: 'foreign key',
+          name: constraintName,
+          references,
+          onDelete,
+          onUpdate: 'CASCADE',
+          transaction,
+        });
+        console.log(`Added FK: ${constraintName}`);
+      }
+    };
+
+    // Use helper multiple times
+    await addForeignKey('assets', 'projectId', { table: 'projects', field: 'id' }, 'CASCADE');
+    await addForeignKey('tour_pages', 'projectId', { table: 'projects', field: 'id' }, 'CASCADE');
+    // ... more FKs
+  },
+};
+```
+
+**Used in:** Foreign key constraints, column removal, index management
+
+---
+
+### 4. Safe Table Drop Pattern
+**Purpose:** Prevent accidental data loss when dropping tables.
+
+```javascript
+module.exports = {
+  async up(queryInterface) {
+    // Verify table is empty before dropping
+    const [results] = await queryInterface.sequelize.query(
+      'SELECT COUNT(*) as count FROM table_name'
+    );
+    const count = parseInt(results[0].count, 10);
+
+    if (count > 0) {
+      throw new Error(
+        `Cannot drop table_name: it contains ${count} records. ` +
+        `Please migrate or delete them first.`
+      );
+    }
+
+    await queryInterface.dropTable('table_name');
+    console.log('Dropped table_name (was empty)');
+  },
+
+  async down(queryInterface, Sequelize) {
+    // Full table recreation with all columns, indexes, and constraints
+    await queryInterface.createTable('table_name', {
+      id: { type: Sequelize.UUID, ... },
+      // ... all columns
+    });
+  },
+};
+```
+
+**Used in:** `drop-page-elements-table`, `drop-page-links-table`, `drop-transitions-table`
+
+---
+
+### 5. ENUM to TEXT Conversion Pattern
+**Purpose:** Convert restrictive ENUMs to flexible TEXT while preserving data.
+
+```javascript
+module.exports = {
+  async up(queryInterface, Sequelize) {
+    const transaction = await queryInterface.sequelize.transaction();
+
+    try {
+      // 1. Create temporary TEXT column
+      await queryInterface.addColumn('table', 'column_text', {
+        type: Sequelize.TEXT,
+        allowNull: true,
+      }, { transaction });
+
+      // 2. Copy ENUM values to TEXT
+      await queryInterface.sequelize.query(
+        `UPDATE table SET column_text = column::TEXT`,
+        { transaction }
+      );
+
+      // 3. Drop old ENUM column
+      await queryInterface.removeColumn('table', 'column', { transaction });
+
+      // 4. Rename TEXT column
+      await queryInterface.renameColumn('table', 'column_text', 'column', { transaction });
+
+      // 5. Add NOT NULL constraint
+      await queryInterface.changeColumn('table', 'column', {
+        type: Sequelize.TEXT,
+        allowNull: false,
+      }, { transaction });
+
+      // 6. Drop ENUM type
+      await queryInterface.sequelize.query(
+        `DROP TYPE IF EXISTS "enum_table_column"`,
+        { transaction }
+      );
+
+      await transaction.commit();
+    } catch (error) {
+      await transaction.rollback();
+      throw error;
+    }
+  },
+
+  async down(queryInterface, Sequelize) {
+    // Recreate ENUM type
+    await queryInterface.sequelize.query(`
+      CREATE TYPE "enum_table_column" AS ENUM ('value1', 'value2', 'value3')
+    `);
+    // ... reverse the process
+  },
+};
+```
+
+**Used in:** `convert-element-type-enum-to-text`
+
+---
+
+### 6. Data Backfill Pattern
+**Purpose:** Populate new tables/columns with data from existing records.
+
+```javascript
+// Define default data
+const DEFAULT_ELEMENT_TYPES = [
+  { element_type: 'navigation_next', name: 'Forward Button', sort_order: 1, settings_json: {...} },
+  { element_type: 'navigation_prev', name: 'Back Button', sort_order: 2, settings_json: {...} },
+  // ... more defaults
+];
+
+module.exports = {
+  async up(queryInterface, Sequelize) {
+    // Get existing records
+    const [projects] = await queryInterface.sequelize.query(
+      `SELECT id FROM projects WHERE "deletedAt" IS NULL`,
+      { type: Sequelize.QueryTypes.SELECT }
+    );
+
+    // For each project, check and insert missing records
+    for (const project of projects) {
+      const [existing] = await queryInterface.sequelize.query(
+        `SELECT element_type FROM project_element_defaults
+         WHERE "projectId" = :projectId AND "deletedAt" IS NULL`,
+        { replacements: { projectId: project.id }, type: Sequelize.QueryTypes.SELECT }
+      );
+
+      const existingTypes = new Set(existing.map(d => d.element_type));
+
+      for (const defaultType of DEFAULT_ELEMENT_TYPES) {
+        if (!existingTypes.has(defaultType.element_type)) {
+          await queryInterface.sequelize.query(`
+            INSERT INTO project_element_defaults (...)
+            VALUES (gen_random_uuid(), :element_type, :name, ...)
+          `, { replacements: { ... } });
+        }
+      }
+    }
+  },
+
+  async down(queryInterface) {
+    // Delete only records created by this migration
+    await queryInterface.sequelize.query(
+      `DELETE FROM project_element_defaults WHERE snapshot_version = 1`
+    );
+  },
+};
+```
+
+**Used in:** `backfill-project-element-defaults`, `sync-all-element-type-defaults`
+
+---
+
+### 7. Cross-Environment Data Copy Pattern
+**Purpose:** Copy content between environments (dev → stage → production).
+
+```javascript
+module.exports = {
+  async up(queryInterface, Sequelize) {
+    const projects = await queryInterface.sequelize.query(
+      `SELECT id FROM projects WHERE "deletedAt" IS NULL`,
+      { type: Sequelize.QueryTypes.SELECT }
+    );
+
+    for (const project of projects) {
+      // Check if target environment already has content
+      const [stageCheck] = await queryInterface.sequelize.query(
+        `SELECT COUNT(*)::int as count FROM tour_pages
+         WHERE "projectId" = '${project.id}' AND environment = 'stage'`
+      );
+
+      if (stageCheck?.count > 0) continue;
+
+      // Copy with INSERT...SELECT, generating new UUIDs
+      await queryInterface.sequelize.query(`
+        INSERT INTO tour_pages (id, slug, name, ..., environment, source_key, ...)
+        SELECT
+          gen_random_uuid(),
+          slug, name, ...,
+          'stage',        -- New environment
+          id::text,       -- Track source record for rollback
+          ...
+        FROM tour_pages
+        WHERE "projectId" = '${project.id}' AND environment = 'dev'
+      `);
+
+      // Copy related records using source_key for ID mapping
+      await queryInterface.sequelize.query(`
+        INSERT INTO page_elements (id, ..., "pageId", ...)
+        SELECT
+          gen_random_uuid(), ...,
+          stage_page.id,  -- Map to new page ID
+          ...
+        FROM page_elements pe
+        INNER JOIN tour_pages dev_page ON pe."pageId" = dev_page.id
+        INNER JOIN tour_pages stage_page ON stage_page.source_key = dev_page.id::text
+        WHERE dev_page.environment = 'dev'
+      `);
+    }
+  },
+
+  async down(queryInterface) {
+    // Delete records with source_key (created by migration)
+    await queryInterface.sequelize.query(
+      `DELETE FROM tour_pages WHERE environment = 'stage' AND source_key IS NOT NULL`
+    );
+  },
+};
+```
+
+**Used in:** `copy-dev-to-stage`
+
+---
+
+### 8. JSON Field Transformation Pattern
+**Purpose:** Transform data stored in JSON columns.
+
+```javascript
+module.exports = {
+  async up(queryInterface, Sequelize) {
+    const transaction = await queryInterface.sequelize.transaction();
+
+    try {
+      // Get all records with JSON data
+      const [records] = await queryInterface.sequelize.query(
+        `SELECT id, "projectId", environment, slug, json_column
+         FROM table_name WHERE json_column IS NOT NULL`,
+        { transaction }
+      );
+
+      // Build lookup maps for ID → slug transformations
+      const slugById = new Map();
+      records.forEach(r => slugById.set(r.id, { projectId: r.projectId, slug: r.slug }));
+
+      // Transform each record
+      for (const record of records) {
+        const jsonData = typeof record.json_column === 'string'
+          ? JSON.parse(record.json_column)
+          : record.json_column;
+
+        let hasChanges = false;
+
+        // Transform JSON structure
+        if (jsonData.elements) {
+          jsonData.elements.forEach(element => {
+            if (element.targetPageId) {
+              const target = slugById.get(element.targetPageId);
+              if (target) {
+                element.targetPageSlug = target.slug;
+                delete element.targetPageId;
+                hasChanges = true;
+              }
+            }
+          });
+        }
+
+        if (hasChanges) {
+          await queryInterface.sequelize.query(
+            `UPDATE table_name SET json_column = :json WHERE id = :id`,
+            {
+              replacements: { json: JSON.stringify(jsonData), id: record.id },
+              transaction
+            }
+          );
+        }
+      }
+
+      await transaction.commit();
+    } catch (error) {
+      await transaction.rollback();
+      throw error;
+    }
+  },
+};
+```
+
+**Used in:** `convert-targetpageid-to-slug`
+
+---
+
+### 9. Constraint Enforcement Pattern
+**Purpose:** Add NOT NULL constraints after fixing existing NULL values.
+
+```javascript
+module.exports = {
+  async up(queryInterface) {
+    // First, fix any NULL values
+    await queryInterface.sequelize.query(
+      `UPDATE table_name SET column = 'default' WHERE column IS NULL`
+    );
+
+    // Then add NOT NULL constraint with default
+    await queryInterface.sequelize.query(`
+      ALTER TABLE table_name
+        ALTER COLUMN column SET NOT NULL,
+        ALTER COLUMN column SET DEFAULT 'default'
+    `);
+  },
+
+  async down(queryInterface) {
+    await queryInterface.sequelize.query(`
+      ALTER TABLE table_name
+        ALTER COLUMN column DROP NOT NULL,
+        ALTER COLUMN column DROP DEFAULT
+    `);
+  },
+};
+```
+
+**Used in:** `enforce-environment-not-null`
+
+---
+
+### 10. Safe Down Migration Pattern
+**Purpose:** Handle cases where down migration isn't meaningful.
+
+```javascript
+module.exports = {
+  async up(queryInterface, Sequelize) {
+    // Add/update missing data
+    // ...
+  },
+
+  async down(_queryInterface, _Sequelize) {
+    // This migration only adds missing data, not destructive
+    console.log('No down migration needed - this migration only adds missing data.');
+  },
+};
+```
+
+**Used in:** `sync-all-element-type-defaults`
+
+---
+
+## Migration Categories
+
+### Schema Changes
+| Migration | Description |
+|-----------|-------------|
+| `add-foreign-key-constraints` | Add FK constraints to all model associations |
+| `create-project-element-defaults` | Create new table with indexes |
+| `drop-page-elements-table` | Drop unused table |
+| `drop-page-links-table` | Drop unused table |
+| `drop-transitions-table` | Drop unused table |
+
+### Column Modifications
+| Migration | Description |
+|-----------|-------------|
+| `remove-redundant-deletion-columns` | Remove `is_deleted`, `deleted_at_time` |
+| `remove-project-phase-column` | Remove redundant `phase` column |
+| `remove-entry-page-slug-column` | Remove unused column |
+| `convert-element-type-enum-to-text` | ENUM → TEXT for flexibility |
+| `enforce-environment-not-null` | Add NOT NULL constraint |
+| `remove-unused-theme-columns-from-projects` | Remove `theme_config_json`, `custom_css_json`, `cdn_base_url` |
+| `add-background-video-settings` | Add video playback settings (autoplay, loop, muted, start/end time) to tour_pages |
+| `add-design-dimensions-to-projects` | Add `design_width`, `design_height` to projects table |
+| `add-design-dimensions-to-tour-pages` | Add `design_width`, `design_height` to tour_pages table |
+
+### Table Renames
+| Migration | Description |
+|-----------|-------------|
+| `rename-ui-elements-to-element-type-defaults` | Rename for clarity |
+
+### Data Migrations
+| Migration | Description |
+|-----------|-------------|
+| `backfill-project-element-defaults` | Populate new table for existing projects |
+| `copy-dev-to-stage` | Initialize stage environment |
+| `convert-targetpageid-to-slug` | Transform JSON navigation references |
+| `fix-project-audio-tracks-environment` | Fix environment values |
+| `add-missing-element-type-defaults` | Insert missing default rows |
+| `sync-all-element-type-defaults` | Full sync of all 11 element types |
+| `remove-duplicate-element-type-defaults` | Remove duplicate records created during earlier migrations |
+| `cleanup-invalid-element-type-defaults` | Clean up invalid entries and ensure data integrity |
+
+---
+
+## Foreign Key Strategies
+
+| Strategy | When to Use | Example |
+|----------|-------------|---------|
+| `CASCADE` | Delete child when parent deleted | `assets.projectId → projects.id` |
+| `SET NULL` | Preserve record, nullify FK | `publish_events.userId → users.id` (audit trail) |
+| `SET NULL` + `allowNull: true` | Optional FK | `users.app_roleId → roles.id` |
+
+```javascript
+// CASCADE - delete assets when project is deleted
+await addForeignKey('assets', 'projectId', { table: 'projects', field: 'id' }, 'CASCADE');
+
+// SET NULL - preserve audit log when user is deleted
+await addForeignKey('access_logs', 'userId', { table: 'users', field: 'id' }, 'SET NULL');
+```
+
+---
+
+## Best Practices
+
+### 1. Always Use Transactions
+```javascript
+const transaction = await queryInterface.sequelize.transaction();
+try {
+  // ... operations
+  await transaction.commit();
+} catch (error) {
+  await transaction.rollback();
+  throw error;
+}
+```
+
+### 2. Check Before Modify
+```javascript
+// Always check existence before adding/removing
+const tableExists = await queryInterface.sequelize.query(
+  `SELECT EXISTS (SELECT FROM information_schema.tables WHERE table_name = 'name')`
+);
+```
+
+### 3. Log Progress
+```javascript
+console.log(`Migrating project ${projectId}: ${addedCount} records added`);
+console.log('Migration complete: All foreign keys added');
+```
+
+### 4. Safe Drops
+```javascript
+// Never drop non-empty tables silently
+if (count > 0) {
+  throw new Error(`Cannot drop table: contains ${count} records`);
+}
+```
+
+### 5. Reversible Operations
+```javascript
+// Down migration should restore previous state
+async down(queryInterface, Sequelize) {
+  // Recreate everything that was dropped
+  await queryInterface.createTable('table_name', { ... });
+  await queryInterface.addIndex('table_name', [...]);
+}
+```
+
+### 6. Use Parameterized Queries
+```javascript
+// Good - prevents SQL injection
+await queryInterface.sequelize.query(
+  `UPDATE table SET column = :value WHERE id = :id`,
+  { replacements: { value: 'safe', id: record.id } }
+);
+
+// Avoid - SQL injection risk
+await queryInterface.sequelize.query(
+  `UPDATE table SET column = '${unsafeValue}' WHERE id = '${unsafeId}'`
+);
+```
+
+---
+
+## Running Migrations
+
+### Development
+```bash
+cd backend
+npm run db:migrate
+```
+
+### Server Startup
+Migrations run automatically via `npm start`:
+```json
+{
+  "scripts": {
+    "start": "npm run db:migrate && npm run db:seed && npm run watch"
+  }
+}
+```
+
+### Migration Status
+```bash
+npm run db:migrate:status
+```
+
+### Undo Migrations
+```bash
+# Undo last migration
+npm run db:migrate:undo
+
+# Undo all migrations (dangerous!)
+npm run db:migrate:undo:all
+```
+
+### Create New Migration
+
+Create new migration files manually under `backend/src/db/migrations/` only
+when a schema change is required. Keep every migration reversible or document an
+explicit rollback/backup plan.
+
+---
+
+## Current Migration Inventory
+
+| # | Timestamp | Name | Type |
+|---|-----------|------|------|
+| 1 | 20260319000001 | add-foreign-key-constraints | Schema |
+| 2 | 20260319000002 | remove-redundant-deletion-columns | Column |
+| 3 | 20260326000001 | rename-ui-elements-to-element-type-defaults | Rename |
+| 4 | 20260326000002 | convert-element-type-enum-to-text | Column |
+| 5 | 20260326000003 | create-project-element-defaults | Schema |
+| 6 | 20260326000004 | backfill-project-element-defaults | Data |
+| 7 | 20260326000005 | fix-project-audio-tracks-environment | Data |
+| 8 | 20260326000006 | copy-dev-to-stage | Data |
+| 9 | 20260326043002 | enforce-environment-not-null | Column |
+| 10 | 20260326050442 | remove-project-phase-column | Column |
+| 11 | 20260326054410 | remove-entry-page-slug-column | Column |
+| 12 | 20260326060000 | convert-targetpageid-to-slug | Data |
+| 13 | 20260326060001 | drop-page-elements-table | Schema |
+| 14 | 20260326060002 | drop-page-links-table | Schema |
+| 15 | 20260326060003 | drop-transitions-table | Schema |
+| 16 | 20260326171017 | add-missing-element-type-defaults | Data |
+| 17 | 20260327000001 | sync-all-element-type-defaults | Data |
+| 18 | 20260331024423 | remove-unused-theme-columns-from-projects | Column |
+| 19 | 20260331054340 | remove-duplicate-element-type-defaults | Data |
+| 20 | 20260331063424 | cleanup-invalid-element-type-defaults | Data |
+| 21 | 20260403000001 | add-background-video-settings | Column |
+| 22 | 20260409000001 | add-design-dimensions-to-projects | Column |
+| 23 | 20260409111309 | add-design-dimensions-to-tour-pages | Column |
+| 24 | 20260605000001 | add-background-audio-settings | Column |
+
+---
+
+## Related Documentation
+
+- [DB Models](./db-models.md) - Sequelize model definitions
+- [DB API](./db-api.md) - Database access layer
+- [Database Schema](../database-schema.md) - Complete schema reference
diff --git a/backend/docs/modules/db-models.md b/backend/docs/modules/db-models.md
new file mode 100644
index 0000000..9115ad7
--- /dev/null
+++ b/backend/docs/modules/db-models.md
@@ -0,0 +1,977 @@
+# Backend DB Models Module
+
+## Overview
+
+The DB Models module defines the Sequelize ORM models that map to PostgreSQL database tables. It provides the data layer for the Tour Builder Platform, handling entity definitions, relationships, validations, and lifecycle hooks.
+
+**Location:** `backend/src/db/models/`
+
+**Files:** 22 model-loader entries (20 models + loader + index bridge). During
+the backend TS/ESM migration, model entries have a typed `.ts` source plus a
+typed ESM source file. There is no model-level CommonJS compatibility facade.
+
+| File | Model | Purpose | LOC |
+|------|-------|---------|-----|
+| `index.ts` | - | ESM entrypoint re-exporting `loader.ts` | 1 |
+| `loader.ts` | - | Typed model registry and Sequelize initialization | 128 |
+| `users.ts` + `.js` bridge | `users` | User accounts with authentication | 246 |
+| `projects.ts` + `.js` bridge | `projects` | Virtual tour projects | 211 |
+| `production_presentation_access.ts` + `.js` bridge | `production_presentation_access` | Customer grants for private production presentations | 67 |
+| `tour_pages.ts` + `.js` bridge | `tour_pages` | Individual tour pages with UI schema | 131 |
+| `assets.ts` + `.js` bridge | `assets` | Uploaded media files | 169 |
+| `asset_variants.ts` + `.js` bridge | `asset_variants` | Asset size/format variants | 103 |
+| `roles.ts` + `roles.js` bridge | `roles` | RBAC roles | 85 |
+| `permissions.ts` + `permissions.js` bridge | `permissions` | RBAC permissions | 52 |
+| `project_memberships.ts` + `.js` bridge | `project_memberships` | User-project access | 89 |
+| `publish_events.ts` + `.js` bridge | `publish_events` | Publishing history | 148 |
+| `pwa_caches.ts` + `.js` bridge | `pwa_caches` | PWA offline cache manifests | 84 |
+| `access_logs.ts` + `.js` bridge | `access_logs` | Activity audit trail | 105 |
+| `element_type_defaults.ts` + `.js` bridge | `element_type_defaults` | Global UI element defaults | 91 |
+| `project_element_defaults.ts` + `.js` bridge | `project_element_defaults` | Project-specific element defaults | 101 |
+| `project_audio_tracks.ts` + `.js` bridge | `project_audio_tracks` | Background audio tracks | 103 |
+| `project_transition_settings.ts` + `.js` bridge | `project_transition_settings` | Environment-aware CSS transition settings | 95 |
+| `global_transition_defaults.ts` + `.js` bridge | `global_transition_defaults` | Platform defaults for CSS page transitions | 65 |
+| `global_ui_control_defaults.ts` + `.js` bridge | `global_ui_control_defaults` | Platform defaults for fullscreen, sound, and offline controls | 33 |
+| `project_ui_control_settings.ts` + `.js` bridge | `project_ui_control_settings` | Project/environment overrides for global UI controls | 61 |
+| `presigned_url_requests.ts` + `.js` bridge | `presigned_url_requests` | S3 presigned URL audit | 118 |
+| `file.ts` + `.js` bridge | `file` | Generic file attachments | 53 |
+
+---
+
+## Architecture
+
+### TS/ESM Migration Boundary
+
+The model loader uses explicit typed ESM imports from `backend/src/db/models/`.
+Migrated model definitions use this structure:
+
+- `model-name.ts` contains the typed ESM model factory.
+- `loader.ts` explicitly imports every model factory and builds the Sequelize
+  registry without dynamic CommonJS discovery.
+- `index.ts` is the ESM entrypoint to `loader.ts` used by DB consumers.
+- `backend/src/types/db-models.ts` keeps the service-specific overload facade
+  as reusable TypeScript contracts.
+- Shared model factory contracts live in `backend/src/types/sequelize-models.ts`
+  and use official Sequelize types.
+
+As of 2026-07-01, all model definitions and the model loader use typed ESM
+source. `users.ts` keeps the hook payload typed through reusable
+`UserModelInstance` and `UsersSequelizeModel` contracts without type
+assertions.
+
+`npm run check:esm-boundaries` guards this boundary: new `.js` source or
+CommonJS syntax in `.ts` fails the check unless it is an explicitly documented
+bridge or immutable migration.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Model Loading Flow                              │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────┐
+│   index.ts      │
+│   (entrypoint)  │
+└────────┬────────┘
+         │
+         │ 1. require('./loader.ts')
+         ▼
+┌─────────────────┐
+│   loader.ts     │
+└────────┬────────┘
+         ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Model Files                                   │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐   │
+│  │ users   │ │projects │ │ assets  │ │ roles   │ │ tour_pages  │   │
+│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └──────┬──────┘   │
+│       │           │           │           │             │           │
+│       └───────────┴───────────┴───────────┴─────────────┘           │
+│                               │                                      │
+└───────────────────────────────┼──────────────────────────────────────┘
+                                │
+         3. Call model.associate(db) for each model
+                                ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     Associations Created                             │
+│                                                                      │
+│  users ─────────────┬─── belongsTo ───→ roles (app_role)            │
+│                     ├─── hasMany ─────→ project_memberships          │
+│                     ├─── hasMany ─────→ production_presentation_access│
+│                     ├─── hasMany ─────→ publish_events               │
+│                     └─── belongsToMany → permissions (custom)        │
+│                                                                      │
+│  projects ──────────┬─── hasMany ─────→ tour_pages                   │
+│                     ├─── hasMany ─────→ assets                       │
+│                     ├─── hasMany ─────→ project_memberships          │
+│                     ├─── hasMany ─────→ production_presentation_access│
+│                     └─── hasMany ─────→ publish_events               │
+│                                                                      │
+│  roles ─────────────┬─── belongsToMany → permissions                 │
+│                     └─── hasMany ─────→ users                        │
+└─────────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      Exported db Object                              │
+│  {                                                                   │
+│    users, projects, tour_pages, assets, roles, permissions,         │
+│    project_memberships, publish_events, pwa_caches, access_logs,    │
+│    element_type_defaults, project_element_defaults, ...             │
+│    sequelize,  // Connection instance                                │
+│    Sequelize   // Sequelize library                                  │
+│  }                                                                   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Model Loader
+
+**Locations:**
+- `backend/src/db/models/loader.ts`
+- `backend/src/db/models/index.ts`
+- `backend/src/types/db-models.ts`
+
+`loader.ts` initializes Sequelize, explicitly imports every model factory, and
+calls `associate()` for models that define associations. `index.ts` re-exports
+the typed registry, and `src/types/db-models.ts` provides the overload surface
+for service-specific model calls.
+
+---
+
+## Database Configuration
+
+**Location:** `backend/src/db/db-config.ts`
+
+| Environment | Database | Logging | Notes |
+|-------------|----------|---------|-------|
+| `production` | From env vars | Disabled | Live production |
+| `development` | `db_tour_builder_platform` | Console | Local dev |
+| `dev_stage` | From env vars | Console | Staging server |
+
+---
+
+## Model Definitions
+
+### Common Model Options
+
+All models share these Sequelize options:
+
+```javascript
+{
+  timestamps: true,      // Adds createdAt, updatedAt
+  paranoid: true,        // Soft delete with deletedAt
+  freezeTableName: true, // Use exact model name as table name
+}
+```
+
+### Common Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `UUID` | Primary key (auto-generated UUIDv4) |
+| `importHash` | `STRING(255)` | Unique hash for bulk import deduplication |
+| `createdAt` | `DATE` | Auto-managed creation timestamp |
+| `updatedAt` | `DATE` | Auto-managed update timestamp |
+| `deletedAt` | `DATE` | Soft delete timestamp (paranoid mode) |
+
+### Common Associations
+
+Most models have these standard associations:
+
+```javascript
+// Audit trail associations
+db.MODEL.belongsTo(db.users, { as: 'createdBy' });
+db.MODEL.belongsTo(db.users, { as: 'updatedBy' });
+```
+
+---
+
+## Core Models
+
+### users
+
+**Purpose:** User accounts for authentication and authorization.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `firstName` | TEXT | Yes | - | Trimmed |
+| `lastName` | TEXT | Yes | - | Trimmed |
+| `phoneNumber` | TEXT | Yes | - | - |
+| `email` | TEXT | No | - | isEmail, notEmpty, unique |
+| `password` | TEXT | No | - | Hashed with bcrypt |
+| `disabled` | BOOLEAN | No | false | - |
+| `emailVerified` | BOOLEAN | No | false | - |
+| `emailVerificationToken` | TEXT | Yes | - | - |
+| `emailVerificationTokenExpiresAt` | DATE | Yes | - | - |
+| `passwordResetToken` | TEXT | Yes | - | - |
+| `passwordResetTokenExpiresAt` | DATE | Yes | - | - |
+| `provider` | TEXT | No | 'local' | OAuth provider |
+| `app_roleId` | UUID | Yes | - | FK to roles |
+
+**Indexes:**
+- `email` (unique)
+- `app_roleId`
+- `deletedAt`
+
+**Associations:**
+```javascript
+users.belongsTo(roles, { as: 'app_role' });
+users.belongsToMany(permissions, { as: 'custom_permissions', through: 'usersCustom_permissionsPermissions' });
+users.hasMany(project_memberships, { as: 'project_memberships_user' });
+users.hasMany(presigned_url_requests, { as: 'presigned_url_requests_user' });
+users.hasMany(publish_events, { as: 'publish_events_user' });
+users.hasMany(access_logs, { as: 'access_logs_user' });
+users.hasMany(file, { as: 'avatar', scope: { belongsTo: 'users', belongsToColumn: 'avatar' } });
+```
+
+**Hooks:**
+```javascript
+users.beforeCreate((user) => {
+  // Trim string fields
+  // Auto-verify email for OAuth providers
+  // Generate random password for OAuth if not provided
+});
+
+users.beforeUpdate((user) => {
+  // Trim string fields
+});
+```
+
+---
+
+### projects
+
+**Purpose:** Virtual tour projects container.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `name` | TEXT | No | - | notEmpty, len[1,255] |
+| `slug` | TEXT | No | - | notEmpty, unique, alphanumeric + dashes/underscores |
+| `description` | TEXT | Yes | - | - |
+| `logo_url` | TEXT | Yes | - | - |
+| `favicon_url` | TEXT | Yes | - | - |
+| `og_image_url` | TEXT | Yes | - | - |
+| `production_presentation_visibility` | ENUM | No | public | public, private |
+
+**Indexes:**
+- `slug` (unique)
+- `deletedAt`
+
+**Associations:**
+```javascript
+projects.hasMany(project_memberships, { as: 'project_memberships_project', onDelete: 'CASCADE' });
+projects.hasMany(assets, { as: 'assets_project', onDelete: 'CASCADE' });
+projects.hasMany(presigned_url_requests, { as: 'presigned_url_requests_project', onDelete: 'CASCADE' });
+projects.hasMany(tour_pages, { as: 'tour_pages_project', onDelete: 'CASCADE' });
+projects.hasMany(project_audio_tracks, { as: 'project_audio_tracks_project', onDelete: 'CASCADE' });
+projects.hasMany(project_transition_settings, { as: 'project_transition_settings_project', onDelete: 'CASCADE' });
+projects.hasMany(publish_events, { as: 'publish_events_project', onDelete: 'CASCADE' });
+projects.hasMany(pwa_caches, { as: 'pwa_caches_project', onDelete: 'CASCADE' });
+projects.hasMany(access_logs, { as: 'access_logs_project', onDelete: 'CASCADE' });
+projects.hasMany(project_element_defaults, { as: 'project_element_defaults_project', onDelete: 'CASCADE' });
+projects.hasMany(production_presentation_access, { as: 'production_presentation_access_project', onDelete: 'CASCADE' });
+```
+
+---
+
+### production_presentation_access
+
+**Purpose:** Grants Public-role customer users access to selected private
+production presentations.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `projectId` | UUID | No | - | FK to projects |
+| `userId` | UUID | No | - | FK to users |
+| `createdById` | UUID | Yes | - | FK to users |
+| `updatedById` | UUID | Yes | - | FK to users |
+| `importHash` | STRING(255) | Yes | - | unique |
+
+**Indexes:**
+- `projectId`
+- `userId`
+- `projectId, userId` unique for active rows
+
+**Associations:**
+```javascript
+production_presentation_access.belongsTo(projects, { as: 'project', onDelete: 'CASCADE' });
+production_presentation_access.belongsTo(users, { as: 'user', onDelete: 'CASCADE' });
+production_presentation_access.belongsTo(users, { as: 'createdBy', onDelete: 'SET NULL' });
+production_presentation_access.belongsTo(users, { as: 'updatedBy', onDelete: 'SET NULL' });
+```
+
+---
+
+### tour_pages
+
+**Purpose:** Individual pages within a tour with UI elements schema.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `environment` | ENUM | No | 'dev' | dev, stage, production |
+| `source_key` | TEXT | Yes | - | Original page ID for cloning |
+| `name` | TEXT | No | - | notEmpty, len[1,255] |
+| `slug` | TEXT | No | - | notEmpty, alphanumeric + dashes |
+| `sort_order` | INTEGER | No | 0 | - |
+| `background_image_url` | TEXT | Yes | - | - |
+| `background_video_url` | TEXT | Yes | - | - |
+| `background_audio_url` | TEXT | Yes | - | - |
+| `background_loop` | BOOLEAN | No | false | - |
+| `requires_auth` | BOOLEAN | No | false | - |
+| `ui_schema_json` | JSON | Yes | - | Page elements, links, transitions |
+| `projectId` | UUID | Yes | - | FK to projects |
+
+**Indexes:**
+- `projectId`
+- `[projectId, environment, slug]` (unique) - Composite unique per project+environment
+- `[projectId, environment, sort_order]` - For ordering queries
+- `deletedAt`
+
+**Note:** The `ui_schema_json` field stores all page elements (buttons, hotspots, galleries, tooltips, media players), navigation links, and transition configurations.
+
+---
+
+### roles
+
+**Purpose:** RBAC role definitions.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `name` | TEXT | No | - | notEmpty, len[1,100] |
+| `role_customization` | TEXT | Yes | - | Custom role metadata |
+
+**Associations:**
+```javascript
+roles.belongsToMany(permissions, { as: 'permissions', through: 'rolesPermissionsPermissions' });
+roles.hasMany(users, { as: 'users_app_role', onDelete: 'SET NULL' });
+```
+
+---
+
+### permissions
+
+**Purpose:** Individual permission definitions.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `name` | TEXT | No | - | notEmpty, unique, len[1,100] |
+
+**Permission Naming Convention:** `{ACTION}_{ENTITY}` (e.g., `READ_USERS`, `CREATE_ASSETS`)
+
+---
+
+## Asset Models
+
+### assets
+
+**Purpose:** Uploaded media files (images, videos, audio, documents).
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `name` | TEXT | Yes | - | len[0,255] |
+| `asset_type` | ENUM | No | - | image, video, audio, file |
+| `type` | ENUM | No | 'general' | icon, background_image, audio, video, transition, logo, favicon, document, general |
+| `cdn_url` | TEXT | Yes | - | - |
+| `storage_key` | TEXT | Yes | - | S3/storage path |
+| `mime_type` | TEXT | Yes | - | MIME type format |
+| `size_mb` | DECIMAL | Yes | - | - |
+| `width_px` | INTEGER | Yes | - | Image/video width |
+| `height_px` | INTEGER | Yes | - | Image/video height |
+| `duration_sec` | DECIMAL | Yes | - | Audio/video duration |
+| `checksum` | TEXT | Yes | - | File hash |
+| `is_public` | BOOLEAN | No | false | - |
+| `projectId` | UUID | Yes | - | FK to projects |
+
+**Indexes:**
+- `projectId`
+- `asset_type`
+- `type`
+- `is_public`
+- `deletedAt`
+
+**Associations:**
+```javascript
+assets.hasMany(asset_variants, { as: 'asset_variants_asset', onDelete: 'CASCADE' });
+assets.belongsTo(projects, { as: 'project', onDelete: 'CASCADE' });
+```
+
+---
+
+### asset_variants
+
+**Purpose:** Optimized versions of assets (thumbnails, different formats).
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `variant_type` | ENUM | Yes | - | thumbnail, preview, webp, mp4_low, mp4_high, original |
+| `cdn_url` | TEXT | Yes | - | len[0,2048], URL format |
+| `width_px` | INTEGER | Yes | - | min: 0 |
+| `height_px` | INTEGER | Yes | - | min: 0 |
+| `size_mb` | DECIMAL | Yes | - | min: 0 |
+| `assetId` | UUID | Yes | - | FK to assets |
+
+**Associations:**
+```javascript
+asset_variants.belongsTo(assets, { as: 'asset', onDelete: 'CASCADE' });
+```
+
+---
+
+## Element Defaults Models
+
+### element_type_defaults
+
+**Purpose:** Global platform-wide default settings for UI element types.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `element_type` | TEXT | No | - | notEmpty, unique, len[1,100] |
+| `name` | TEXT | No | - | notEmpty, len[1,255] |
+| `sort_order` | INTEGER | No | 0 | - |
+| `is_active` | VIRTUAL | - | true | Always returns true |
+| `default_settings_json` | TEXT | Yes | - | Mapped from `settings_json` column |
+
+**Indexes:**
+- `element_type`
+- `sort_order`
+- `deletedAt`
+
+**Associations:**
+```javascript
+element_type_defaults.hasMany(project_element_defaults, {
+  as: 'project_defaults',
+  foreignKey: 'source_element_id',
+  onDelete: 'SET NULL'
+});
+```
+
+**Element Types:** button, hotspot, gallery, tooltip, video_player, audio_player, image, text, link, form, iframe
+
+---
+
+### project_element_defaults
+
+**Purpose:** Project-specific overrides for element defaults.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `element_type` | TEXT | No | - | notEmpty, len[1,100] |
+| `name` | TEXT | Yes | - | len[0,255] |
+| `sort_order` | INTEGER | No | 0 | - |
+| `settings_json` | TEXT | Yes | - | Element configuration |
+| `source_element_id` | UUID | Yes | - | FK to element_type_defaults |
+| `snapshot_version` | INTEGER | No | 1 | Version tracking |
+| `projectId` | UUID | No | - | FK to projects |
+
+**Indexes:**
+- `projectId`
+- `[projectId, element_type]` (unique)
+- `element_type`
+- `source_element_id`
+- `deletedAt`
+
+**Associations:**
+```javascript
+project_element_defaults.belongsTo(projects, { as: 'project', onDelete: 'CASCADE' });
+project_element_defaults.belongsTo(element_type_defaults, {
+  as: 'source_element',
+  onDelete: 'SET NULL'
+});
+```
+
+---
+
+## Publishing & Audit Models
+
+### publish_events
+
+**Purpose:** Track publishing actions between environments.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `title` | STRING | Yes | - | len[0,255] |
+| `description` | TEXT | Yes | - | len[0,5000] |
+| `from_environment` | ENUM | No | - | dev, stage, production |
+| `to_environment` | ENUM | No | - | dev, stage, production |
+| `started_at` | DATE | Yes | - | - |
+| `finished_at` | DATE | Yes | - | - |
+| `status` | ENUM | No | 'queued' | queued, running, success, failed |
+| `error_message` | TEXT | Yes | - | - |
+| `pages_copied` | INTEGER | Yes | - | min: 0 |
+| `transitions_copied` | INTEGER | Yes | - | min: 0 |
+| `audios_copied` | INTEGER | Yes | - | min: 0 |
+| `projectId` | UUID | Yes | - | FK to projects |
+| `userId` | UUID | Yes | - | FK to users |
+
+**Indexes:**
+- `projectId`
+- `userId`
+- `status`
+- `started_at`
+
+---
+
+### access_logs
+
+**Purpose:** Audit trail for user activity.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `environment` | ENUM | No | - | admin, stage, production |
+| `path` | TEXT | Yes | - | len[0,2048] |
+| `ip_address` | TEXT | Yes | - | len[0,45] (IPv6 max) |
+| `user_agent` | TEXT | Yes | - | len[0,1024] |
+| `accessed_at` | DATE | No | NOW | - |
+| `projectId` | UUID | Yes | - | FK to projects |
+| `userId` | UUID | Yes | - | FK to users |
+
+**Indexes:**
+- `projectId`
+- `environment`
+- `userId`
+- `accessed_at`
+
+---
+
+## Supporting Models
+
+### project_memberships
+
+**Purpose:** User access to projects with role-based permissions.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `access_level` | ENUM | No | 'viewer' | owner, editor, reviewer, viewer |
+| `is_active` | BOOLEAN | No | false | - |
+| `invited_at` | DATE | Yes | - | - |
+| `accepted_at` | DATE | Yes | - | - |
+| `projectId` | UUID | Yes | - | FK to projects |
+| `userId` | UUID | Yes | - | FK to users |
+
+**Indexes:**
+- `projectId`
+- `userId`
+- `[projectId, userId]` (unique) - One membership per user per project
+- `is_active`
+- `deletedAt`
+
+---
+
+### project_audio_tracks
+
+**Purpose:** Background audio tracks for projects.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `environment` | ENUM | Yes | - | dev, stage, production |
+| `source_key` | TEXT | Yes | - | Original track ID for cloning |
+| `name` | TEXT | Yes | - | len[0,255] |
+| `slug` | TEXT | Yes | - | - |
+| `url` | TEXT | Yes | - | - |
+| `loop` | BOOLEAN | No | false | - |
+| `volume` | DECIMAL | Yes | - | min: 0, max: 1 |
+| `sort_order` | INTEGER | Yes | - | - |
+| `is_enabled` | BOOLEAN | No | false | - |
+| `projectId` | UUID | Yes | - | FK to projects |
+
+---
+
+### project_transition_settings
+
+**Purpose:** Environment-aware CSS transition settings for page navigation.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `environment` | ENUM | No | - | dev, stage, production |
+| `source_key` | TEXT | Yes | - | Original settings ID for cloning |
+| `transition_type` | TEXT | No | 'fade' | CSS transition type |
+| `duration_ms` | INTEGER | No | 700 | Transition duration in ms |
+| `easing` | TEXT | No | 'ease-in-out' | CSS easing function |
+| `overlay_color` | TEXT | No | '#000000' | Transition overlay color |
+| `projectId` | UUID | No | - | FK to projects |
+| `createdById` | UUID | Yes | - | FK to users |
+| `updatedById` | UUID | Yes | - | FK to users |
+
+**Indexes:**
+- `[projectId, environment]` (unique where deletedAt IS NULL)
+- `projectId`
+- `deletedAt`
+
+**Associations:**
+```javascript
+project_transition_settings.belongsTo(projects, { as: 'project', onDelete: 'CASCADE' });
+project_transition_settings.belongsTo(users, { as: 'createdBy' });
+project_transition_settings.belongsTo(users, { as: 'updatedBy' });
+```
+
+**Publishing Integration:** Copied between environments during Save to Stage (dev → stage) and Publish (stage → production). Uses `source_key` to track lineage.
+
+---
+
+### pwa_caches
+
+**Purpose:** PWA offline cache manifest tracking.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `environment` | ENUM | Yes | - | dev, stage, production |
+| `cache_version` | TEXT | Yes | - | len[0,255] |
+| `manifest_json` | JSON | Yes | - | PWA manifest |
+| `asset_list_json` | JSON | Yes | - | Cached asset URLs |
+| `generated_at` | DATE | Yes | - | - |
+| `is_active` | BOOLEAN | No | false | - |
+| `projectId` | UUID | Yes | - | FK to projects |
+
+---
+
+### presigned_url_requests
+
+**Purpose:** Audit log for S3 presigned URL requests.
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `purpose` | ENUM | Yes | - | upload, download |
+| `asset_type` | ENUM | Yes | - | image, video, audio, file |
+| `requested_key` | TEXT | Yes | - | len[0,1024] |
+| `mime_type` | TEXT | Yes | - | MIME format, len[0,255] |
+| `requested_size_mb` | DECIMAL | Yes | - | min: 0 |
+| `expires_at` | DATE | Yes | - | - |
+| `status` | TEXT | Yes | - | - |
+| `projectId` | UUID | Yes | - | FK to projects |
+| `userId` | UUID | Yes | - | FK to users |
+
+---
+
+### file
+
+**Purpose:** Generic file attachments (user avatars, etc.).
+
+| Field | Type | Nullable | Default | Validation |
+|-------|------|----------|---------|------------|
+| `id` | UUID | No | UUIDv4 | - |
+| `belongsTo` | STRING(255) | Yes | - | Parent table name |
+| `belongsToId` | UUID | Yes | - | Parent record ID |
+| `belongsToColumn` | STRING(255) | Yes | - | Parent column name |
+| `name` | STRING(2083) | No | - | notEmpty |
+| `sizeInBytes` | INTEGER | Yes | - | - |
+| `privateUrl` | STRING(2083) | Yes | - | - |
+| `publicUrl` | STRING(2083) | No | - | notEmpty |
+
+**Usage Pattern:** Polymorphic association via `belongsTo`, `belongsToId`, `belongsToColumn` fields and scoped `hasMany` on parent models:
+
+```javascript
+// In users model:
+db.users.hasMany(db.file, {
+  as: 'avatar',
+  foreignKey: 'belongsToId',
+  scope: {
+    belongsTo: 'users',
+    belongsToColumn: 'avatar',
+  },
+});
+```
+
+---
+
+## Entity Relationship Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Entity Relationships                                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                              ┌─────────────┐
+                              │    roles    │
+                              │             │
+                              │ name        │
+                              │ permissions │◄─── M:N ───┐
+                              └──────┬──────┘            │
+                                     │                   │
+                                     │ 1:N               │
+                                     │                   │
+┌─────────────────────────┐   ┌──────▼──────┐   ┌───────┴───────┐
+│  element_type_defaults  │   │    users    │   │  permissions  │
+│                         │   │             │   │               │
+│ element_type            │   │ email       │   │ name          │
+│ name                    │   │ password    │   │               │
+│ settings_json           │   │ app_role ───┼───┘               │
+└───────────┬─────────────┘   └──────┬──────┘                   │
+            │                        │                          │
+            │ 1:N                    │ 1:N                      │
+            │                        │                          │
+            ▼                        ▼                          │
+┌───────────────────────┐   ┌────────────────────┐              │
+│project_element_defaults│   │project_memberships │              │
+│                       │   │                    │              │
+│ element_type          │   │ access_level       │              │
+│ settings_json         │   │ is_active          │              │
+│ source_element_id ────┼───┘                    │              │
+│ projectId ────────────┼───┐                    │              │
+└───────────────────────┘   │                    │              │
+                            │                    │              │
+                            │ N:1                │ N:1          │
+                            │                    │              │
+                            ▼                    ▼              │
+                      ┌─────────────────────────────────────┐   │
+                      │              projects               │   │
+                      │                                     │   │
+                      │ name, slug, description             │   │
+                      │ logo_url, favicon_url, og_image_url │   │
+                      └───────────────┬─────────────────────┘   │
+                                      │                         │
+        ┌─────────────┬───────────────┼───────────────┬─────────┘
+        │             │               │               │
+        │ 1:N         │ 1:N           │ 1:N           │ 1:N
+        ▼             ▼               ▼               ▼
+┌───────────────┐ ┌───────────┐ ┌───────────────┐ ┌───────────────┐
+│  tour_pages   │ │  assets   │ │publish_events │ │  pwa_caches   │
+│               │ │           │ │               │ │               │
+│ environment   │ │ asset_type│ │ status        │ │ environment   │
+│ name, slug    │ │ cdn_url   │ │ from/to_env   │ │ manifest_json │
+│ ui_schema_json│ │ storage_key│ │ pages_copied │ │ asset_list    │
+└───────────────┘ └─────┬─────┘ └───────────────┘ └───────────────┘
+                        │
+                        │ 1:N
+                        ▼
+                  ┌─────────────────┐
+                  │ asset_variants  │
+                  │                 │
+                  │ variant_type    │
+                  │ cdn_url         │
+                  │ width_px        │
+                  └─────────────────┘
+
+
+Additional Models (project-scoped):
+  • project_audio_tracks → projects (N:1)
+  • project_transition_settings → projects (N:1)
+  • production_presentation_access → projects (N:1), users (N:1)
+  • access_logs → projects (N:1), users (N:1)
+  • presigned_url_requests → projects (N:1), users (N:1)
+```
+
+---
+
+## Model Patterns
+
+### 1. Soft Delete (Paranoid Mode)
+
+All models use `paranoid: true`, which adds a `deletedAt` column and modifies queries:
+
+```javascript
+// This:
+await Model.destroy({ where: { id } });
+
+// Does NOT delete, but sets deletedAt = NOW()
+// All find queries automatically filter deletedAt IS NULL
+```
+
+### 2. Environment Enum
+
+Several models use the environment enum for multi-environment content:
+
+```javascript
+environment: {
+  type: DataTypes.ENUM,
+  values: ['dev', 'stage', 'production'],
+}
+```
+
+**Used by:** tour_pages, project_audio_tracks, project_transition_settings, pwa_caches, publish_events
+
+### 3. Import Hash Deduplication
+
+The `importHash` field prevents duplicate imports:
+
+```javascript
+importHash: {
+  type: DataTypes.STRING(255),
+  allowNull: true,
+  unique: true,
+}
+```
+
+### 4. Cascade Delete Patterns
+
+| Relationship | onDelete | Use Case |
+|--------------|----------|----------|
+| `CASCADE` | Delete children when parent deleted | Projects → tour_pages |
+| `SET NULL` | Keep children, null the FK | Roles → users |
+
+### 5. Composite Unique Constraints
+
+For scoped uniqueness:
+
+```javascript
+indexes: [
+  { fields: ['projectId', 'environment', 'slug'], unique: true },
+]
+```
+
+### 6. JSON Fields
+
+Complex configurations stored as JSON:
+
+```javascript
+ui_schema_json: { type: DataTypes.JSON }     // Parsed JSON column
+settings_json: { type: DataTypes.TEXT }       // Stringified JSON text
+```
+
+### 7. Virtual Fields
+
+Computed fields that don't exist in the database:
+
+```javascript
+is_active: {
+  type: DataTypes.VIRTUAL,
+  get() {
+    return true;
+  },
+}
+```
+
+---
+
+## Validation Patterns
+
+### String Length
+
+```javascript
+name: {
+  type: DataTypes.TEXT,
+  validate: {
+    len: {
+      args: [1, 255],
+      msg: 'Name must be between 1 and 255 characters',
+    },
+  },
+}
+```
+
+### Required Fields
+
+```javascript
+email: {
+  type: DataTypes.TEXT,
+  allowNull: false,
+  validate: {
+    notEmpty: { msg: 'Email is required' },
+  },
+}
+```
+
+### Email Format
+
+```javascript
+email: {
+  validate: {
+    isEmail: { msg: 'Must be a valid email address' },
+  },
+}
+```
+
+### Custom Validators
+
+```javascript
+cdn_url: {
+  validate: {
+    isUrlOrEmpty(value) {
+      if (value && value.length > 0 && !/^https?:\/\/.+/.test(value)) {
+        throw new Error('CDN URL must be a valid URL');
+      }
+    },
+  },
+}
+```
+
+### Numeric Range
+
+```javascript
+volume: {
+  type: DataTypes.DECIMAL,
+  validate: {
+    min: { args: [0], msg: 'Volume must be at least 0' },
+    max: { args: [1], msg: 'Volume must be at most 1' },
+  },
+}
+```
+
+---
+
+## Usage Examples
+
+### Importing Models
+
+```javascript
+const db = require('./db/models');
+
+// Access models
+const user = await db.users.findByPk(id);
+const project = await db.projects.findOne({ where: { slug } });
+
+// Access Sequelize instance
+const transaction = await db.sequelize.transaction();
+
+// Access Sequelize operators
+const { Op } = db.Sequelize;
+const users = await db.users.findAll({
+  where: { email: { [Op.like]: '%@example.com' } }
+});
+```
+
+### Creating Records with Associations
+
+```javascript
+const project = await db.projects.create({
+  name: 'My Tour',
+  slug: 'my-tour',
+  createdById: userId,
+});
+
+const page = await db.tour_pages.create({
+  name: 'Home',
+  slug: 'home',
+  projectId: project.id,
+  environment: 'dev',
+  createdById: userId,
+});
+```
+
+### Querying with Includes
+
+```javascript
+const project = await db.projects.findOne({
+  where: { id: projectId },
+  include: [
+    { association: 'tour_pages_project', where: { environment: 'production' } },
+    { association: 'project_memberships_project', include: ['user'] },
+  ],
+});
+```
+
+---
+
+## Related Documentation
+
+- [Database Schema](../database-schema.md) - Complete schema reference
+- [Factories Module](./factories.md) - Service and router factories that use models
+- [Services Module](./services.md) - Business logic using models
+- [API Endpoints](../api-endpoints.md) - REST API exposing models
diff --git a/backend/docs/modules/db-seeders.md b/backend/docs/modules/db-seeders.md
new file mode 100644
index 0000000..2d2b042
--- /dev/null
+++ b/backend/docs/modules/db-seeders.md
@@ -0,0 +1,575 @@
+# DB Seeders Module
+
+## Overview
+
+The DB Seeders module provides initial data population for the database using
+the typed **Umzug v3** runner in `backend/src/db/umzug.ts`. Seeders create
+essential system data (users, roles, permissions) and optional sample data for
+development and testing.
+
+**Location:** `backend/src/db/seeders/`
+
+**Files:** 3 TypeScript ESM seeder entries. There are no JavaScript seeder
+bridges after the backend ESM migration.
+
+---
+
+## Architecture
+
+```
+backend/src/db/seeders/
+├── 20200430130759-admin-user.ts       # Initial admin users
+├── 20200430130760-user-roles.ts       # RBAC roles + permissions
+└── 20231127130745-sample-data.ts      # Sample data, opt-in
+```
+
+**Execution Order:** Seeders run in timestamp order (oldest first).
+
+---
+
+## Configuration
+
+### NPM Scripts
+```bash
+# Run pending seeders
+npm run db:seed
+
+# Undo all seeders
+npm run db:seed:undo
+
+# Full database reset (includes seeding)
+npm run db:reset
+```
+
+### Server Startup
+Seeders run automatically via `npm start`:
+```json
+{
+  "scripts": {
+    "start": "npm run db:migrate && npm run db:seed && npm run watch"
+  }
+}
+```
+
+---
+
+## Seeder Files
+
+### 1. Admin User Seeder (`20200430130759-admin-user.ts`)
+
+**Purpose:** Create initial system users.
+
+The implementation uses reusable contracts from
+`backend/src/types/db-seeders.ts`. Umzug executes the TypeScript source in
+development and the compiled JavaScript file from `dist/` in production builds.
+
+**Users Created:**
+
+| User | Email | Role Assignment |
+|------|-------|-----------------|
+| Admin | `config.admin_email` | Administrator |
+| John | john@doe.com | Account Manager |
+| Client | client@hello.com | Platform Owner |
+
+**Key Features:**
+- Uses bcrypt for password hashing with configured salt rounds
+- Hardcoded UUIDs for consistent user IDs
+- Reads credentials from `config.ts` (environment variables)
+- Idempotent on repeated `db:seed`: existing seed user IDs are selected first,
+  and only missing rows are inserted. This prevents duplicate-key failures when
+  `SequelizeData` lacks the seeder entry but users already exist.
+
+```typescript
+const existingRows =
+  await queryInterface.sequelize.query<AdminUserSeedExistingIdRow>(
+    'SELECT "id" FROM "users" WHERE "id" IN (:ids)',
+    {
+      replacements: { ids: seedUserIds },
+      type: QueryTypes.SELECT,
+    },
+  );
+
+const existingIds = new Set(existingRows.map((row) => row.id));
+const rowsToInsert = createAdminUserRows().filter(
+  (row) => !existingIds.has(row.id),
+);
+
+if (rowsToInsert.length > 0) {
+  await queryInterface.bulkInsert('users', rowsToInsert);
+}
+```
+
+---
+
+### 2. User Roles Seeder (`20200430130760-user-roles.ts`)
+
+**Purpose:** Create the complete RBAC (Role-Based Access Control) system.
+
+The implementation uses reusable contracts from
+`backend/src/types/db-seeders.ts`. Umzug stores stable seeder execution names
+in `SequelizeData` so repeated startup seeding does not rerun completed seed
+data.
+
+**Data Created:**
+
+| Data Type | Count | Description |
+|-----------|-------|-------------|
+| Roles | 7 | User role definitions |
+| Permissions | 54 | CRUD permissions for 13 entities + special |
+| Role-Permission Links | 200+ | M:N relationships |
+| Join Table | 1 | `rolesPermissionsPermissions` table |
+
+**Key Features:**
+- Uses stable named role and permission definitions, then reuses existing DB IDs
+  when the same role/permission name is already present.
+- Inserts only missing roles, permissions, and role-permission links. This keeps
+  repeated `db:seed` safe.
+- Keeps the existing startup behavior that assigns system users to seeded roles
+  by email after RBAC data exists.
+
+#### Roles
+```javascript
+const roles = [
+  'Administrator',      // Full system access
+  'PlatformOwner',      // Full project/content access
+  'AccountManager',     // User and project management
+  'TourDesigner',       // Content creation and editing
+  'ContentReviewer',    // Read + limited update access
+  'AnalyticsViewer',    // Read-only access
+  'Public',             // Public/unauthenticated access
+];
+```
+
+#### Permission Generation Pattern
+```javascript
+// Generates CREATE, READ, UPDATE, DELETE permissions per entity
+function createPermissions(name) {
+  return [
+    { name: `CREATE_${name.toUpperCase()}` },
+    { name: `READ_${name.toUpperCase()}` },
+    { name: `UPDATE_${name.toUpperCase()}` },
+    { name: `DELETE_${name.toUpperCase()}` },
+  ];
+}
+
+const entities = [
+  'users', 'roles', 'permissions', 'projects', 'project_memberships',
+  'assets', 'asset_variants', 'presigned_url_requests', 'tour_pages',
+  'project_audio_tracks', 'publish_events', 'pwa_caches', 'access_logs'
+];
+
+// Creates 52 permissions (13 entities × 4 CRUD operations)
+await queryInterface.bulkInsert('permissions', entities.flatMap(createPermissions));
+
+// Plus special permissions
+await queryInterface.bulkInsert('permissions', [
+  { name: 'READ_API_DOCS' },
+  { name: 'CREATE_SEARCH' },
+]);
+```
+
+#### ID Map Pattern
+```javascript
+// Consistent UUID generation using key-based map
+const idMap = new Map();
+
+function getId(key) {
+  if (idMap.has(key)) {
+    return idMap.get(key);
+  }
+  const id = uuid();
+  idMap.set(key, id);
+  return id;
+}
+
+// Usage - same key always returns same UUID within seeder run
+getId('Administrator')  // Returns consistent UUID
+getId('CREATE_USERS')   // Returns consistent UUID
+```
+
+#### Permission Matrix
+
+| Role | Users | Projects | Assets | Tour Pages | Access Logs |
+|------|-------|----------|--------|------------|-------------|
+| **Administrator** | CRUD | CRUD | CRUD | CRUD | CRUD |
+| **PlatformOwner** | CRUD | CRUD | CRUD | CRUD | CRUD |
+| **AccountManager** | RU | CRU | CRU | CRU | R |
+| **TourDesigner** | R | RU | CRU | CRU | R |
+| **ContentReviewer** | R | RU | RU | RU | R |
+| **AnalyticsViewer** | R | R | R | R | R |
+| **Public** | - | - | - | - | - |
+
+**Legend:** C=Create, R=Read, U=Update, D=Delete
+
+#### Join Table Creation
+```javascript
+// Creates M:N relationship table directly in seeder
+await queryInterface.sequelize.query(`
+  CREATE TABLE IF NOT EXISTS "rolesPermissionsPermissions" (
+    "createdAt" timestamp with time zone not null,
+    "updatedAt" timestamp with time zone not null,
+    "roles_permissionsId" uuid not null,
+    "permissionId" uuid not null,
+    primary key ("roles_permissionsId", "permissionId"),
+    constraint "rolesPermissionsPermissions_roles_permissions_fk"
+      foreign key ("roles_permissionsId") references "roles"("id")
+      on delete cascade on update cascade,
+    constraint "rolesPermissionsPermissions_permission_fk"
+      foreign key ("permissionId") references "permissions"("id")
+      on delete cascade on update cascade
+  );
+`);
+```
+
+---
+
+### 3. Sample Data Seeder (`20231127130745-sample-data.ts`)
+
+**Purpose:** Create sample data for development and testing.
+
+The implementation lives in `20231127130745-sample-data.ts`. Demo-only
+Sequelize operations use reusable `SampleDataModel` and
+`SampleDataAssociationRecord` contracts from
+`backend/src/types/db-seeders.ts`; the production service model overloads stay
+separate. Umzug records the seeder under its legacy `.js` name for storage
+compatibility only.
+
+**Opt-In Activation:**
+```bash
+# Enable sample data seeding
+export ENABLE_SAMPLE_DATA=true
+npm run db:seed
+```
+
+**Check in Code:**
+```typescript
+const sampleDataSeeder: SequelizeSeeder = {
+  async up() {
+    if (process.env.ENABLE_SAMPLE_DATA !== 'true') return;
+    // ... seed data
+  },
+};
+```
+
+**Data Created:**
+
+| Entity | Records | Description |
+|--------|---------|-------------|
+| Projects | 3 | Sample tour projects |
+| Project Memberships | 3 | User-project associations |
+| Assets | 3 | Images, videos, audio |
+| Asset Variants | 3 | Thumbnail/preview variants |
+| Presigned URL Requests | 3 | Upload/download requests |
+| Tour Pages | 3 | Sample tour pages |
+| Project Audio Tracks | 3 | Background audio |
+| Publish Events | 3 | Deployment history |
+| PWA Caches | 3 | Offline cache configs |
+| Access Logs | 3 | Visitor tracking |
+
+#### Sample Projects
+```javascript
+const ProjectsData = [
+  {
+    name: 'Cardiff Arena Tour',
+    slug: 'cardiff-arena',
+    description: 'Interactive arena tour for visitors and event planners.',
+    logo_url: 'https://cdn.platform.com/cardiff/logo.png',
+    favicon_url: 'https://cdn.platform.com/cardiff/favicon.ico',
+    og_image_url: 'https://cdn.platform.com/cardiff/og.jpg',
+  },
+  {
+    name: 'Riverside Park Walkthrough',
+    slug: 'riverside-park',
+    description: 'Offline-ready guided walkthrough for the city park.',
+    // ...
+  },
+  {
+    name: 'Mall Central Experience',
+    slug: 'mall-central',
+    description: 'Retail complex presentation with navigation and galleries.',
+    // ...
+  },
+];
+```
+
+#### Association Helper Pattern
+```javascript
+// Associates records after bulk creation using Sequelize model methods
+async function associateAssetWithProject() {
+  const relatedProject = await Projects.findOne({
+    offset: Math.floor(Math.random() * (await Projects.count())),
+  });
+  const asset = await Assets.findOne({
+    order: [['id', 'ASC']],
+    offset: 0,
+  });
+  if (asset?.setProject) {
+    await asset.setProject(relatedProject);
+  }
+}
+```
+
+---
+
+## Seeder Patterns
+
+### 1. bulkInsert Pattern
+**Purpose:** Insert multiple records efficiently.
+
+```javascript
+await queryInterface.bulkInsert('tableName', [
+  {
+    id: uuid(),
+    field1: 'value1',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  },
+  // ... more records
+]);
+```
+
+### 2. bulkDelete Pattern
+**Purpose:** Remove seeded data during rollback.
+
+```javascript
+async down(queryInterface, Sequelize) {
+  await queryInterface.bulkDelete('users', {
+    id: { [Sequelize.Op.in]: ids }
+  });
+}
+```
+
+### 3. Conditional Execution Pattern
+**Purpose:** Enable/disable seeders based on environment.
+
+Seeder-only environment gates are intentionally allowed to read `process.env`
+directly. Runtime app configuration must go through `backend/src/config.ts`,
+but seeders and scripts are bootstrap/data-loading entrypoints and are listed
+as exceptions in `AGENTS.md`.
+
+The resilience/config hardening work does not require seeder changes because it
+does not introduce database schema, RBAC permissions, seed users, roles, default
+records, or sample-data entities.
+
+```javascript
+up: async () => {
+  if (process.env.ENABLE_SAMPLE_DATA !== 'true') {
+    return;  // Skip seeding
+  }
+  // ... proceed with seeding
+}
+```
+
+### 4. ID Consistency Pattern
+**Purpose:** Use deterministic IDs for reliable down() migrations.
+
+```javascript
+// Hardcoded IDs for rollback capability
+const ids = [
+  '193bf4b5-9f07-4bd5-9a43-e7e41f3e96af',
+  'af5a87be-8f9c-4630-902a-37a60b7005ba',
+];
+
+// OR: Map-based consistent generation
+const idMap = new Map();
+function getId(key) {
+  if (!idMap.has(key)) {
+    idMap.set(key, uuid());
+  }
+  return idMap.get(key);
+}
+```
+
+### 5. Model-Based Association Pattern
+**Purpose:** Create relationships using Sequelize models after bulk insert.
+
+```javascript
+// Use model methods for associations (more readable)
+const project = await Projects.findOne({ where: { slug: 'test' } });
+const asset = await Assets.findOne({ order: [['id', 'ASC']] });
+await asset.setProject(project);
+```
+
+### 6. Raw SQL Pattern
+**Purpose:** Create structures not managed by Sequelize models.
+
+```javascript
+// Create join table directly via SQL
+await queryInterface.sequelize.query(`
+  CREATE TABLE IF NOT EXISTS "rolesPermissionsPermissions" (
+    ...
+  );
+`);
+
+// Create indexes
+await queryInterface.sequelize.query(
+  'CREATE INDEX IF NOT EXISTS "index_name" ON "tableName" ("columnName");'
+);
+```
+
+---
+
+## Execution Flow
+
+```
+npm run db:seed
+    │
+    ▼
+┌────────────────────────────────────┐
+│ 20200430130759-admin-user.ts       │
+│   ├─ Typed ESM source              │
+│   ├─ Hash passwords                │
+│   └─ Insert missing seed users      │
+└────────────────────────────────────┘
+    │
+    ▼
+┌────────────────────────────────────┐
+│ 20200430130760-user-roles.ts       │
+│   ├─ Typed ESM source              │
+│   ├─ Insert missing roles          │
+│   ├─ Insert missing permissions    │
+│   ├─ Create join table             │
+│   ├─ Insert missing RBAC links      │
+│   └─ Update user app_roleId        │
+└────────────────────────────────────┘
+    │
+    ▼
+┌────────────────────────────────────┐
+│ 20231127130745-sample-data.ts      │
+│   ├─ Check ENABLE_SAMPLE_DATA      │
+│   ├─ Skip if not enabled           │
+│   ├─ Insert sample records         │
+│   └─ Create associations           │
+└────────────────────────────────────┘
+```
+
+---
+
+## Best Practices
+
+### 1. Use Consistent IDs
+```javascript
+// Good - allows rollback
+const ids = ['uuid-1', 'uuid-2'];
+await queryInterface.bulkInsert('table', records.map((r, i) => ({ id: ids[i], ...r })));
+
+// Down migration can target specific IDs
+await queryInterface.bulkDelete('table', { id: { [Op.in]: ids } });
+```
+
+### 2. Always Include Timestamps
+```javascript
+{
+  field: 'value',
+  createdAt: new Date(),
+  updatedAt: new Date(),
+}
+```
+
+### 3. Handle Errors
+```javascript
+try {
+  await queryInterface.bulkInsert('users', [...]);
+} catch (error) {
+  console.error('Error during bulkInsert:', error);
+  throw error;
+}
+```
+
+### 4. Environment-Aware Seeding
+```javascript
+// Production - only essential data
+// Development - include sample data
+if (process.env.ENABLE_SAMPLE_DATA !== 'true') {
+  return;
+}
+```
+
+### 5. Idempotent Where Possible
+```javascript
+// Use IF NOT EXISTS for table/index creation
+await queryInterface.sequelize.query(`
+  CREATE TABLE IF NOT EXISTS "tableName" (...)
+`);
+
+await queryInterface.sequelize.query(`
+  CREATE INDEX IF NOT EXISTS "indexName" ON "tableName" (...)
+`);
+```
+
+---
+
+## Data Dependencies
+
+```
+admin-user.ts
+    │
+    │ Creates missing users with stable IDs
+    ▼
+user-roles.ts
+    │
+    │ Creates/reuses roles and permissions, then references user emails to assign roles
+    │ UPDATE users SET app_roleId = '...' WHERE email = '...'
+    ▼
+sample-data.ts
+    │
+    │ Uses Sequelize models to find existing users/projects
+    │ Creates associations via model methods
+    ▼
+```
+
+---
+
+## Running Seeders
+
+### Development Setup
+```bash
+cd backend
+npm run db:seed
+```
+
+### With Sample Data
+```bash
+export ENABLE_SAMPLE_DATA=true
+npm run db:seed
+```
+
+### Fresh Database
+```bash
+npm run db:reset  # drop, create, migrate, seed
+```
+
+### Undo Seeders
+```bash
+npm run db:seed:undo  # Runs all down() methods in reverse order
+```
+
+---
+
+## Seeder Inventory
+
+| # | Timestamp | Name | Records | Required |
+|---|-----------|------|---------|----------|
+| 1 | 20200430130759 | admin-user | 3 users | Yes |
+| 2 | 20200430130760 | user-roles | 7 roles, 54 permissions, 200+ links | Yes |
+| 3 | 20231127130745 | sample-data | 30+ sample records | No (opt-in) |
+
+---
+
+## Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `ENABLE_SAMPLE_DATA` | Enable sample data seeder | `false` |
+| `ADMIN_EMAIL` | Admin user email | (from config) |
+| `ADMIN_PASS` | Admin user password | (from config) |
+| `USER_PASS` | Default user password | (from config) |
+
+---
+
+## Related Documentation
+
+- [DB Migrations](./db-migrations.md) - Schema evolution
+- [DB Models](./db-models.md) - Sequelize model definitions
+- [RBAC System](../../../documentation/rbac-system.md) - Role-based access control details
+- [Authentication](./auth.md) - User authentication
diff --git a/backend/docs/modules/email.md b/backend/docs/modules/email.md
new file mode 100644
index 0000000..417b328
--- /dev/null
+++ b/backend/docs/modules/email.md
@@ -0,0 +1,961 @@
+# Backend Email Module
+
+## Overview
+
+The Email module provides transactional email functionality for user authentication flows including email verification, password reset, and user invitations. It uses **Nodemailer** with **AWS SES** (Simple Email Service) as the SMTP transport.
+
+**Location:** `backend/src/services/email/`
+
+**Total Files:** 7
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Auth Service                                 │
+│  (services/auth.ts)                                                 │
+│                                                                     │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐  │
+│  │     signup()    │  │    signin()     │  │ sendPasswordReset() │  │
+│  └────────┬────────┘  └─────────────────┘  └──────────┬──────────┘  │
+│           │                                           │             │
+│           │ sends verification                        │ sends reset │
+│           ▼                                           ▼             │
+└───────────┼───────────────────────────────────────────┼─────────────┘
+            │                                           │
+            ▼                                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                       Email Module                                  │
+│  (services/email/)                                                  │
+│                                                                     │
+│  ┌─────────────────────────────────────────────────────────────┐    │
+│  │                     EmailSender                             │    │
+│  │                     (index.js)                              │    │
+│  │  • Nodemailer transport                                     │    │
+│  │  • AWS SES configuration                                    │    │
+│  │  • send() method                                            │    │
+│  └─────────────────────────────────────────────────────────────┘    │
+│                              │                                      │
+│           ┌──────────────────┼──────────────────┐                   │
+│           ▼                  ▼                  ▼                   │
+│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐           │
+│  │PasswordReset   │ │ AddressVerif.  │ │  Invitation    │           │
+│  │    Email       │ │    Email       │ │    Email       │           │
+│  └───────┬────────┘ └───────┬────────┘ └───────┬────────┘           │
+│          │                  │                  │                    │
+│          ▼                  ▼                  ▼                    │
+│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐           │
+│  │ passwordReset  │ │ addressVerif.  │ │  invitation    │           │
+│  │  Email.html    │ │  Email.html    │ │ Template.html  │           │
+│  └────────────────┘ └────────────────┘ └────────────────┘           │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    AWS SES (SMTP)                                   │
+│            email-smtp.us-east-1.amazonaws.com:587                   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Directory Structure
+
+```
+services/email/
+├── index.js                      # EmailSender class (45 LOC)
+├── list/                         # Email template classes
+│   ├── passwordReset.ts          # Password reset email
+│   ├── addressVerification.ts    # Email verification email
+│   └── invitation.ts             # User invitation email
+└── htmlTemplates/                # HTML email templates
+    ├── passwordReset/
+    │   └── passwordResetEmail.html    (52 LOC)
+    ├── addressVerification/
+    │   └── emailAddressVerification.html (52 LOC)
+    └── invitation/
+        └── invitationTemplate.html    (55 LOC)
+```
+
+---
+
+## Core Components
+
+### EmailSender Class (`index.ts`)
+
+The main email sending service using Nodemailer.
+
+```typescript
+import nodemailer from 'nodemailer';
+import type SMTPTransport from 'nodemailer/lib/smtp-transport';
+
+import config from '../../config.ts';
+import type { EmailSendResult, EmailTemplate } from '../../types/index.js';
+
+export default class EmailSender {
+  constructor(private readonly email: EmailTemplate) {}
+
+  async send(): Promise<EmailSendResult> {
+    const htmlContent = await this.email.html();
+    const transporter = nodemailer.createTransport(this.transportConfig);
+    const mailOptions: SMTPTransport.MailOptions = {
+      from: this.from,
+      to: this.email.to,
+      subject: this.email.subject,
+      html: htmlContent,
+      headers: {
+        'X-SES-CONFIGURATION-SET': 'flatlogic-app',
+      },
+    };
+
+    return transporter.sendMail(mailOptions);
+  }
+
+  static get isConfigured(): boolean {
+    return Boolean(config.email.auth.pass && config.email.auth.user);
+  }
+
+  get transportConfig(): SMTPTransport.Options {
+    return config.email;
+  }
+
+  get from(): string {
+    return config.email.from;
+  }
+}
+```
+
+**Key Methods:**
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `constructor(email)` | Instance | Accepts email template object |
+| `send()` | Async | Sends email via Nodemailer |
+| `isConfigured` | Static getter | Checks if SMTP credentials exist |
+| `transportConfig` | Getter | Returns SMTP config |
+| `from` | Getter | Returns sender address |
+
+---
+
+## Email Templates
+
+### Template Interface
+
+All email templates implement the same interface:
+
+```typescript
+interface EmailTemplate {
+  to: string;
+  subject: string;
+  html(): Promise<string> | string;
+}
+```
+
+### 1. Password Reset Email (`list/passwordReset.ts`)
+
+Sent when user requests password reset.
+
+```typescript
+export default class PasswordResetEmail implements EmailTemplate {
+  constructor({ to, link }: LinkEmailTemplateOptions) {
+    this.to = to;
+    this.link = link;
+  }
+
+  get subject() {
+    return getNotification(
+      'emails.passwordReset.subject',
+      getNotification('app.title')
+    );
+    // → "Reset your password for Tour Builder Platform"
+  }
+
+  async html() {
+    const template = await fs.readFile(templatePath, 'utf8');
+    return template
+      .replace(/{appTitle}/g, appTitle)
+      .replace(/{resetUrl}/g, this.link)
+      .replace(/{accountName}/g, this.to);
+  }
+};
+```
+
+**Template Variables:**
+- `{appTitle}` - Application name
+- `{resetUrl}` - Password reset link
+- `{accountName}` - User email address
+
+### 2. Email Verification (`list/addressVerification.ts`)
+
+Sent after user registration.
+
+```typescript
+export default class EmailAddressVerificationEmail implements EmailTemplate {
+  constructor({ to, link }: LinkEmailTemplateOptions) {
+    this.to = to;
+    this.link = link;
+  }
+
+  get subject() {
+    return getNotification(
+      'emails.emailAddressVerification.subject',
+      getNotification('app.title')
+    );
+    // → "Verify your email for Tour Builder Platform"
+  }
+
+  async html() {
+    const template = await fs.readFile(templatePath, 'utf8');
+    return template
+      .replace(/{appTitle}/g, appTitle)
+      .replace(/{signupUrl}/g, this.link)
+      .replace(/{to}/g, this.to);
+  }
+};
+```
+
+**Template Variables:**
+- `{appTitle}` - Application name
+- `{signupUrl}` - Email verification link
+- `{to}` - User email address
+
+### 3. User Invitation (`list/invitation.ts`)
+
+Sent when admin invites new user.
+
+```typescript
+export default class InvitationEmail implements EmailTemplate {
+  constructor({ to, host }: InvitationEmailTemplateOptions) {
+    this.to = to;
+    this.host = host;
+  }
+
+  get subject() {
+    return getNotification(
+      'emails.invitation.subject',
+      getNotification('app.title')
+    );
+    // → "You've been invited to Tour Builder Platform"
+  }
+
+  async html() {
+    const template = await fs.readFile(templatePath, 'utf8');
+    const signupUrl = `${this.host}&invitation=true`;
+    return template
+      .replace(/{appTitle}/g, appTitle)
+      .replace(/{signupUrl}/g, signupUrl)
+      .replace(/{to}/g, this.to);
+  }
+};
+```
+
+**Template Variables:**
+- `{appTitle}` - Application name
+- `{signupUrl}` - Account setup link with `&invitation=true`
+- `{to}` - User email address
+
+---
+
+## HTML Email Templates
+
+### Template Structure
+
+All HTML templates follow consistent styling:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <style>
+        .email-container {
+            max-width: 600px;
+            margin: auto;
+            background-color: #ffffff;
+            border: 1px solid #e2e8f0;
+            border-radius: 4px;
+            overflow: hidden;
+        }
+        .email-header {
+            background-color: #3498db;  /* Primary blue */
+            color: #fff;
+            padding: 16px;
+            text-align: center;
+        }
+        .email-body {
+            padding: 16px;
+        }
+        .email-footer {
+            padding: 16px;
+            background-color: #f7fafc;
+            text-align: center;
+            color: #4a5568;
+            font-size: 14px;
+        }
+        .link-primary {
+            color: #3498db;
+            text-decoration: none;
+        }
+        .btn-primary {
+            background-color: #3498db;
+            color: #fff !important;
+            padding: 8px 16px;
+            border-radius: 4px;
+            text-decoration: none;
+            display: inline-block;
+        }
+    </style>
+</head>
+<body>
+    <div class="email-container">
+        <div class="email-header">...</div>
+        <div class="email-body">...</div>
+        <div class="email-footer">
+            Thanks,<br/>
+            The {appTitle} Team
+        </div>
+    </div>
+</body>
+</html>
+```
+
+### Template Comparison
+
+| Template | Header Text | Call-to-Action | Button Style |
+|----------|-------------|----------------|--------------|
+| Password Reset | "Reset your password for {appTitle}" | Link | Text link |
+| Email Verification | "Verify your email for {appTitle}!" | Link | Text link |
+| Invitation | "Welcome to {appTitle}!" | Button | Primary button |
+
+---
+
+## Configuration
+
+### SMTP Settings (`config.ts`)
+
+```javascript
+email: {
+  from: 'Tour Builder Platform <app@flatlogic.app>',
+  host: 'email-smtp.us-east-1.amazonaws.com',
+  port: 587,
+  auth: {
+    user: process.env.EMAIL_USER || '',
+    pass: process.env.EMAIL_PASS,
+  },
+  tls: {
+    rejectUnauthorized: process.env.EMAIL_TLS_REJECT_UNAUTHORIZED !== 'false',
+  },
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `EMAIL_USER` | Yes | SMTP username (AWS SES IAM user) |
+| `EMAIL_PASS` | Yes | SMTP password (AWS SES IAM credentials) |
+| `EMAIL_TLS_REJECT_UNAUTHORIZED` | No | Set to `'false'` to skip TLS verification |
+
+### AWS SES Configuration
+
+The system uses AWS SES in the `us-east-1` region:
+
+```
+Host: email-smtp.us-east-1.amazonaws.com
+Port: 587 (STARTTLS)
+Authentication: SMTP credentials from IAM
+Configuration Set: flatlogic-app
+```
+
+---
+
+## Integration Points
+
+### Auth Service Integration
+
+The Auth service (`services/auth.ts`) is the primary consumer:
+
+```typescript
+import EmailAddressVerificationEmail from './email/list/addressVerification.ts';
+import InvitationEmail from './email/list/invitation.ts';
+const PasswordResetEmail = require('./email/list/passwordReset.ts').default;
+const EmailSender = require('./email/index.ts').default;
+
+class Auth {
+  // Called during signup
+  static async sendEmailAddressVerificationEmail(email, host) {
+    const token = await UsersDBApi.generateEmailVerificationToken(email);
+    const link = `${host}/verify-email?token=${token}`;
+
+    const emailObj = new EmailAddressVerificationEmail({ to: email, link });
+    return new EmailSender(emailObj).send();
+  }
+
+  // Called for password reset or invitation
+  static async sendPasswordResetEmail(email, type = 'register', host) {
+    const token = await UsersDBApi.generatePasswordResetToken(email);
+    const link = `${host}/password-reset?token=${token}`;
+
+    const emailObj = type === 'invitation'
+      ? new InvitationEmail({ to: email, host: link })
+      : new PasswordResetEmail({ to: email, link });
+
+    return new EmailSender(emailObj).send();
+  }
+}
+```
+
+### Users Service Integration
+
+User invitations are sent when creating users:
+
+```javascript
+// services/users.ts
+static async create({ data, currentUser, sendInvitationEmails = true, host }) {
+  // ... create user ...
+
+  if (sendInvitationEmails) {
+    AuthService.sendPasswordResetEmail(email, 'invitation', host);
+  }
+}
+
+static async bulkImport(req, res, sendInvitationEmails = true, host) {
+  // ... import users from CSV ...
+
+  if (!sendInvitationEmails) {
+    emailsToInvite.forEach((email) => {
+      AuthService.sendPasswordResetEmail(email, 'invitation', host);
+    });
+  }
+}
+```
+
+### Auth Routes Integration
+
+Auth routes expose email functionality:
+
+```javascript
+// routes/auth.js
+
+// Check if email is configured (public)
+router.get('/email-configured', (req, res) => {
+  const payload = EmailSender.isConfigured;
+  res.status(200).send(payload);
+});
+
+// Resend verification email (authenticated)
+router.put('/send-email-address-verification-email', jwtAuth, async (req, res) => {
+  await AuthService.sendEmailAddressVerificationEmail(req.currentUser.email);
+  res.status(200).send(true);
+});
+
+// Request password reset (public)
+router.put('/send-password-reset-email', async (req, res) => {
+  const host = getRequestHost(req);
+  await AuthService.sendPasswordResetEmail(req.body.email, 'register', host);
+  res.status(200).send(true);
+});
+```
+
+---
+
+## Token Management
+
+### Token Generation
+
+Tokens are generated in `db/api/users.js`:
+
+```javascript
+static async _generateToken(keyNames, email, options) {
+  const users = await db.users.findOne({
+    where: { email: email.toLowerCase() },
+    transaction,
+  });
+
+  const token = crypto.randomBytes(20).toString('hex');
+  const TOKEN_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24 hours
+  const tokenExpiresAt = Date.now() + TOKEN_EXPIRY_MS;
+
+  if (users) {
+    await users.update({
+      [keyNames[0]]: token,           // emailVerificationToken or passwordResetToken
+      [keyNames[1]]: tokenExpiresAt,  // ...ExpiresAt
+      updatedById: currentUser.id,
+    }, { transaction });
+  }
+
+  return token;
+}
+
+static async generateEmailVerificationToken(email, options) {
+  return this._generateToken(
+    ['emailVerificationToken', 'emailVerificationTokenExpiresAt'],
+    email, options
+  );
+}
+
+static async generatePasswordResetToken(email, options) {
+  return this._generateToken(
+    ['passwordResetToken', 'passwordResetTokenExpiresAt'],
+    email, options
+  );
+}
+```
+
+### Token Validation
+
+```javascript
+static async findByPasswordResetToken(token, options) {
+  return db.users.findOne({
+    where: {
+      passwordResetToken: token,
+      passwordResetTokenExpiresAt: {
+        [db.Sequelize.Op.gt]: Date.now(),  // Not expired
+      },
+    },
+    transaction,
+  });
+}
+
+static async findByEmailVerificationToken(token, options) {
+  return db.users.findOne({
+    where: {
+      emailVerificationToken: token,
+      emailVerificationTokenExpiresAt: {
+        [db.Sequelize.Op.gt]: Date.now(),
+      },
+    },
+    transaction,
+  });
+}
+
+static async markEmailVerified(id, options) {
+  const user = await db.users.findByPk(id, { transaction });
+  await user.update({
+    emailVerified: true,
+    emailVerificationToken: null,
+    emailVerificationTokenExpiresAt: null,
+  }, { transaction });
+}
+```
+
+### Token Properties
+
+| Token Type | Field | Expiry Field | TTL |
+|------------|-------|--------------|-----|
+| Email Verification | `emailVerificationToken` | `emailVerificationTokenExpiresAt` | 24 hours |
+| Password Reset | `passwordResetToken` | `passwordResetTokenExpiresAt` | 24 hours |
+
+---
+
+## Email Flows
+
+### 1. User Registration Flow
+
+```
+┌────────────┐     ┌──────────────┐     ┌─────────────┐
+│   User     │────▶│  POST /auth  │────▶│ Auth.signup │
+│  Signs Up  │     │   /signup    │     │             │
+└────────────┘     └──────────────┘     └──────┬──────┘
+                                               │
+                                               ▼
+                   ┌──────────────────────────────────────────┐
+                   │  if (EmailSender.isConfigured) {         │
+                   │    await sendEmailAddressVerification(); │
+                   │  }                                       │
+                   └───────────────────┬──────────────────────┘
+                                       │
+                    ┌──────────────────┼──────────────────┐
+                    ▼                                     ▼
+           ┌────────────────┐                   ┌────────────────┐
+           │ Generate Token │                   │    Skip        │
+           │ (24hr expiry)  │                   │ (not configured)│
+           └───────┬────────┘                   └────────────────┘
+                   │
+                   ▼
+           ┌────────────────┐
+           │  Send Email    │
+           │ (verification) │
+           └───────┬────────┘
+                   │
+                   ▼
+           ┌────────────────┐
+           │  User clicks   │
+           │ /verify-email  │
+           │   ?token=xxx   │
+           └───────┬────────┘
+                   │
+                   ▼
+           ┌────────────────┐
+           │ Auth.verifyEmail│
+           │ markEmailVerified│
+           └────────────────┘
+```
+
+### 2. Password Reset Flow
+
+```
+┌────────────┐     ┌────────────────────┐     ┌───────────────────────┐
+│   User     │────▶│  PUT /auth/send-   │────▶│ Auth.sendPassword     │
+│ Forgot Pwd │     │ password-reset-email│    │    ResetEmail()       │
+└────────────┘     └────────────────────┘     └───────────┬───────────┘
+                                                          │
+                                                          ▼
+                                              ┌───────────────────────┐
+                                              │ generatePasswordReset │
+                                              │    Token (24hr)       │
+                                              └───────────┬───────────┘
+                                                          │
+                                                          ▼
+                                              ┌───────────────────────┐
+                                              │    Send Email         │
+                                              │ (PasswordResetEmail)  │
+                                              └───────────┬───────────┘
+                                                          │
+                                                          ▼
+                                              ┌───────────────────────┐
+                                              │   User clicks         │
+                                              │ /password-reset       │
+                                              │    ?token=xxx         │
+                                              └───────────┬───────────┘
+                                                          │
+                                                          ▼
+                                              ┌───────────────────────┐
+                                              │  PUT /auth/password-  │
+                                              │      reset            │
+                                              │ { token, password }   │
+                                              └───────────────────────┘
+```
+
+### 3. User Invitation Flow
+
+```
+┌────────────┐     ┌──────────────┐     ┌─────────────────┐
+│   Admin    │────▶│ POST /users  │────▶│ UsersService    │
+│ Creates    │     │  { email }   │     │   .create()     │
+│   User     │     └──────────────┘     └────────┬────────┘
+└────────────┘                                   │
+                                                 ▼
+                                    ┌─────────────────────────┐
+                                    │ AuthService.sendPassword│
+                                    │ ResetEmail(email,       │
+                                    │   'invitation', host)   │
+                                    └────────────┬────────────┘
+                                                 │
+                                                 ▼
+                                    ┌─────────────────────────┐
+                                    │   InvitationEmail       │
+                                    │ (Welcome to {appTitle}!)│
+                                    └────────────┬────────────┘
+                                                 │
+                                                 ▼
+                                    ┌─────────────────────────┐
+                                    │   User clicks link      │
+                                    │ /password-reset?token=  │
+                                    │    xxx&invitation=true  │
+                                    └────────────┬────────────┘
+                                                 │
+                                                 ▼
+                                    ┌─────────────────────────┐
+                                    │   Sets password         │
+                                    │   (account activated)   │
+                                    └─────────────────────────┘
+```
+
+---
+
+## Email Behavior Modes
+
+### Email Configured Mode
+
+When `EMAIL_USER` and `EMAIL_PASS` are set:
+- Email verification required before login
+- Password reset emails sent on request
+- User invitations include email
+
+### Email Not Configured Mode
+
+When credentials are missing:
+- `EmailSender.isConfigured` returns `false`
+- Users auto-verified on signin: `user.emailVerified = true`
+- Password reset/invitation silently skipped
+- Frontend adapts UI accordingly
+
+```javascript
+// Auth service adapts behavior
+static async signin(email, password) {
+  // ...
+  if (!EmailSender.isConfigured) {
+    user.emailVerified = true;  // Auto-verify when email disabled
+  }
+
+  if (!user.emailVerified) {
+    throw new ValidationError('auth.userNotVerified');
+  }
+  // ...
+}
+```
+
+---
+
+## Notification Catalog
+
+Email subjects use the notification system (`services/notifications/list.ts`):
+
+```javascript
+emails: {
+  invitation: {
+    subject: "You've been invited to {0}",
+    body: `
+      <p>Hello,</p>
+      <p>You've been invited to {0} set password for your {1} account.</p>
+      <p><a href='{2}'>{2}</a></p>
+      <p>Thanks,</p>
+      <p>Your {0} team</p>
+    `,
+  },
+  emailAddressVerification: {
+    subject: "Verify your email for {0}",
+    body: `
+      <p>Hello,</p>
+      <p>Follow this link to verify your email address.</p>
+      <p><a href='{0}'>{0}</a></p>
+      <p>If you didn't ask to verify this address, you can ignore this email.</p>
+      <p>Thanks,</p>
+      <p>Your {1} team</p>
+    `,
+  },
+  passwordReset: {
+    subject: "Reset your password for {0}",
+    body: `
+      <p>Hello,</p>
+      <p>Follow this link to reset your {0} password for your {1} account.</p>
+      <p><a href='{2}'>{2}</a></p>
+      <p>If you didn't ask to reset your password, you can ignore this email.</p>
+      <p>Thanks,</p>
+      <p>Your {0} team</p>
+    `,
+  },
+}
+```
+
+---
+
+## Error Handling
+
+### Email-Related Errors
+
+| Error Code | Message | When Thrown |
+|------------|---------|-------------|
+| `auth.emailAddressVerificationEmail.error` | "Email not recognized" | Token generation fails |
+| `auth.emailAddressVerificationEmail.invalidToken` | "Email verification link is invalid or has expired" | Invalid/expired verification token |
+| `auth.passwordReset.error` | "Email not recognized" | Password reset token generation fails |
+| `auth.passwordReset.invalidToken` | "Password reset link is invalid or has expired" | Invalid/expired reset token |
+| `auth.userNotVerified` | "Sorry, your email has not been verified yet" | Login without email verification |
+
+### Error Flow
+
+```javascript
+static async sendEmailAddressVerificationEmail(email, host) {
+  let link;
+  try {
+    const token = await UsersDBApi.generateEmailVerificationToken(email);
+    link = `${host}/verify-email?token=${token}`;
+  } catch (error) {
+    console.error(error);
+    throw new ValidationError('auth.emailAddressVerificationEmail.error');
+  }
+
+  // Create and send email
+  const emailObj = new EmailAddressVerificationEmail({ to: email, link });
+  return new EmailSender(emailObj).send();
+}
+```
+
+---
+
+## Testing
+
+### Unit Testing Email Templates
+
+```javascript
+describe('PasswordResetEmail', () => {
+  it('should generate correct subject', () => {
+    const email = new PasswordResetEmail({
+      to: 'user@example.com',
+      link: 'https://app.com/reset?token=abc',
+    });
+    expect(email.subject).toBe('Reset your password for Tour Builder Platform');
+  });
+
+  it('should render HTML with placeholders', async () => {
+    const email = new PasswordResetEmail({
+      to: 'user@example.com',
+      link: 'https://app.com/reset?token=abc',
+    });
+    const html = await email.html();
+
+    expect(html).toContain('Tour Builder Platform');
+    expect(html).toContain('https://app.com/reset?token=abc');
+    expect(html).toContain('user@example.com');
+  });
+});
+```
+
+### Integration Testing Email Sending
+
+```javascript
+describe('EmailSender', () => {
+  it('should validate required fields', async () => {
+    const sender = new EmailSender({});
+    await expect(sender.send()).rejects.toThrow('email.to is required');
+  });
+
+  it('should send email via nodemailer', async () => {
+    const mockTransport = { sendMail: jest.fn().mockResolvedValue({}) };
+    jest.spyOn(nodemailer, 'createTransport').mockReturnValue(mockTransport);
+
+    const email = new PasswordResetEmail({
+      to: 'test@example.com',
+      link: 'https://example.com',
+    });
+    const sender = new EmailSender(email);
+    await sender.send();
+
+    expect(mockTransport.sendMail).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: 'test@example.com',
+        subject: expect.stringContaining('Reset your password'),
+      })
+    );
+  });
+});
+```
+
+### Testing Without SMTP
+
+Set credentials to empty for local development:
+
+```bash
+EMAIL_USER=
+EMAIL_PASS=
+```
+
+Result:
+- `EmailSender.isConfigured` returns `false`
+- Users auto-verified on login
+- No emails sent
+
+---
+
+## Customization
+
+### Adding New Email Template
+
+1. **Create HTML template:**
+
+```html
+<!-- services/email/htmlTemplates/welcome/welcomeEmail.html -->
+<!DOCTYPE html>
+<html>
+<head>
+    <style>/* Same styles as other templates */</style>
+</head>
+<body>
+<div class="email-container">
+    <div class="email-header">Welcome to {appTitle}!</div>
+    <div class="email-body">
+        <p>Hello {userName},</p>
+        <p>Your account has been activated.</p>
+    </div>
+    <div class="email-footer">Thanks,<br/>The {appTitle} Team</div>
+</div>
+</body>
+</html>
+```
+
+2. **Create email class:**
+
+```javascript
+// services/email/list/welcome.ts
+import { promises as fs } from 'fs';
+import path from 'path';
+
+import { getNotification } from '../../notifications/helpers.ts';
+import type { EmailTemplate } from '../../../types/index.js';
+
+interface WelcomeEmailOptions {
+  to: string;
+  userName: string;
+}
+
+export default class WelcomeEmail implements EmailTemplate {
+  to: string;
+  private readonly userName: string;
+
+  constructor({ to, userName }: WelcomeEmailOptions) {
+    this.to = to;
+    this.userName = userName;
+  }
+
+  get subject(): string {
+    return getNotification('emails.welcome.subject', getNotification('app.title'));
+  }
+
+  async html(): Promise<string> {
+    const templatePath = path.resolve(
+      process.cwd(),
+      'src/services/email/htmlTemplates/welcome/welcomeEmail.html',
+    );
+    const template = await fs.readFile(templatePath, 'utf8');
+    const appTitle = getNotification('app.title');
+
+    return template
+      .replace(/{appTitle}/g, appTitle)
+      .replace(/{userName}/g, this.userName);
+  }
+};
+```
+
+3. **Add notification entry:**
+
+```typescript
+// services/notifications/list.ts
+emails: {
+  // ... existing ...
+  welcome: {
+    subject: "Welcome to {0}!",
+    body: "...",
+  },
+}
+```
+
+4. **Use in service:**
+
+```typescript
+import WelcomeEmail from './email/list/welcome.ts';
+
+const email = new WelcomeEmail({ to: 'user@example.com', userName: 'John' });
+await new EmailSender(email).send();
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `nodemailer` | ^6.x | SMTP transport |
+| `assert` | built-in | Input validation |
+| `fs.promises` | built-in | Template file reading |
+| `path` | built-in | Template path resolution |
+
+---
+
+## Related Documentation
+
+- [Auth Module](./auth.md) - Authentication service integration
+- [Services Module](./services.md) - Service layer overview
+- [Notifications Module](./notifications.md) - Error messages and i18n
+- [User Management](../../../documentation/user-management.md) - User invitation flow
diff --git a/backend/docs/modules/factories.md b/backend/docs/modules/factories.md
new file mode 100644
index 0000000..6837f39
--- /dev/null
+++ b/backend/docs/modules/factories.md
@@ -0,0 +1,846 @@
+# Backend Factories Module
+
+## Overview
+
+The Factories module provides code generation patterns that eliminate boilerplate for standard CRUD operations across the backend. Two factory functions generate consistent, standardized router and service classes for all entity types.
+
+**Location:** `backend/src/factories/`
+
+**Files:**
+| File | Purpose | LOC |
+|------|---------|-----|
+| `router.factory.ts` | Generates Express routers with CRUD endpoints | 429 |
+| `service.factory.ts` | Generates service classes with transaction handling | 350 |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Factory Pattern Flow                            │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│  Route File     │    │  Service File   │    │  DB API File    │
+│  (3-5 lines)    │    │  (3-5 lines)    │    │  (extends base) │
+└────────┬────────┘    └────────┬────────┘    └────────┬────────┘
+         │                      │                      │
+         ▼                      ▼                      ▼
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│ createEntity    │    │ createEntity    │    │ GenericDBApi    │
+│ Router()        │    │ Service()       │    │ (base.api.ts)   │
+└────────┬────────┘    └────────┬────────┘    └────────┬────────┘
+         │                      │                      │
+         └──────────────────────┼──────────────────────┘
+                                │
+                                ▼
+                    ┌───────────────────────┐
+                    │   Sequelize Model     │
+                    │   (db/models/*.js)    │
+                    └───────────────────────┘
+
+Boilerplate Reduction:
+- Without factories: ~300-500 lines per entity
+- With factories: ~10-20 lines per entity (97% reduction)
+```
+
+---
+
+## Factory Files
+
+### router.factory.ts
+
+**Purpose:** Generates Express routers with standardized CRUD endpoints, permission checking, CSV export, and error handling.
+
+**Location:** `backend/src/factories/router.factory.ts`
+
+#### Function Signature
+
+```javascript
+function createEntityRouter(entityName, Service, DBApi, options = {})
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `entityName` | `string` | Entity name for routes and permissions |
+| `Service` | `class` | Service class with CRUD methods |
+| `DBApi` | `class` | Database API class extending GenericDBApi |
+| `options` | `object` | Configuration options |
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `permissionEntity` | `string` | `entityName` | Override permission entity name |
+| `csvFields` | `string[]` | `DBApi.CSV_FIELDS` | Fields to include in CSV export |
+| `customRoutes` | `function` | `null` | Callback to add custom routes |
+
+#### Generated Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/` | Create new record |
+| `POST` | `/bulk-import` | Bulk import from CSV |
+| `PUT` | `/:id` | Update record by ID |
+| `DELETE` | `/:id` | Delete record by ID |
+| `POST` | `/deleteByIds` | Delete multiple records |
+| `GET` | `/` | List all records (with filters, pagination) |
+| `GET` | `/count` | Get record count |
+| `GET` | `/autocomplete` | Get autocomplete suggestions |
+| `GET` | `/:id` | Get single record by ID |
+
+#### Implementation
+
+```javascript
+const express = require('express');
+const { wrapAsync, commonErrorHandler, isUuidV4 } = require('../helpers');
+const { checkCrudPermissions } = require('../middlewares/check-permissions');
+const { parse } = require('json2csv');
+
+function createEntityRouter(entityName, Service, DBApi, options = {}) {
+  const router = express.Router();
+
+  // Apply CRUD permission middleware for all routes
+  const permissionEntity = options.permissionEntity || entityName;
+  router.use(checkCrudPermissions(permissionEntity));
+
+  // POST / - Create
+  router.post('/', wrapAsync(async (req, res) => {
+    const referer = req.headers.referer || `${req.protocol}://${req.hostname}${req.originalUrl}`;
+    const link = new URL(referer);
+    const payload = await Service.create({
+      data: req.body.data,
+      currentUser: req.currentUser,
+      runtimeContext: req.runtimeContext,
+      sendInvitationEmails: true,
+      host: link.host,
+    });
+    res.status(200).send(payload);
+  }));
+
+  // POST /bulk-import - Bulk CSV import
+  router.post('/bulk-import', wrapAsync(async (req, res) => {
+    const referer = req.headers.referer || `${req.protocol}://${req.hostname}${req.originalUrl}`;
+    const link = new URL(referer);
+    await Service.bulkImport(req, res, true, link.host);
+    res.status(200).send(true);
+  }));
+
+  // PUT /:id - Update
+  router.put('/:id', wrapAsync(async (req, res) => {
+    assertRouteIdMatchesBody(req);
+    await Service.update({
+      id: req.params.id,
+      data: req.body.data,
+      currentUser: req.currentUser,
+      runtimeContext: req.runtimeContext,
+    });
+    res.status(200).send(true);
+  }));
+
+  // DELETE /:id - Delete single
+  router.delete('/:id', wrapAsync(async (req, res) => {
+    await Service.remove({
+      id: req.params.id,
+      currentUser: req.currentUser,
+      runtimeContext: req.runtimeContext,
+    });
+    res.status(200).send(true);
+  }));
+
+  // POST /deleteByIds - Delete multiple
+  router.post('/deleteByIds', wrapAsync(async (req, res) => {
+    await Service.deleteByIds({
+      ids: req.body.data,
+      currentUser: req.currentUser,
+      runtimeContext: req.runtimeContext,
+    });
+    res.status(200).send(true);
+  }));
+
+  // GET / - List all with optional CSV export
+  router.get('/', wrapAsync(async (req, res) => {
+    const filetype = req.query.filetype;
+    const currentUser = req.currentUser;
+    const runtimeContext = req.runtimeContext;
+
+    const payload = await DBApi.findAll(normalizeQuery(req.query, DBApi, {
+      csv: filetype === 'csv',
+    }), { currentUser, runtimeContext });
+
+    if (filetype === 'csv') {
+      const fields = options.csvFields || DBApi.CSV_FIELDS || ['id', 'createdAt'];
+      const opts = { fields };
+      try {
+        const csv = parse(payload.rows, opts);
+        res.status(200).attachment('export.csv').send(csv);
+      } catch (err) {
+        logger.error({ err, entityName }, 'CSV export error');
+        res.status(500).send('CSV export error');
+      }
+    } else {
+      res.status(200).send(payload);
+    }
+  }));
+
+  // GET /count - Count only
+  router.get('/count', wrapAsync(async (req, res) => {
+    const currentUser = req.currentUser;
+    const runtimeContext = req.runtimeContext;
+    const payload = await DBApi.findAll(normalizeQuery(req.query, DBApi), { countOnly: true, currentUser, runtimeContext });
+    res.status(200).send(payload);
+  }));
+
+  // GET /autocomplete - Autocomplete search
+  router.get('/autocomplete', wrapAsync(async (req, res) => {
+    const payload = await DBApi.findAllAutocomplete({
+      query: req.query.query,
+      limit,
+      offset: req.query.offset,
+    });
+    res.status(200).send(payload);
+  }));
+
+  // GET /:id - Find by ID
+  router.get('/:id', wrapAsync(async (req, res) => {
+    if (!isUuidV4(req.params.id)) {
+      return res.status(400).send(`Invalid ${entityName} id`);
+    }
+    const runtimeContext = req.runtimeContext;
+    const payload = await DBApi.findBy({ id: req.params.id }, { runtimeContext });
+    res.status(200).send(payload);
+  }));
+
+  // Custom routes hook
+  if (options.customRoutes) {
+    options.customRoutes(router, Service, DBApi);
+  }
+
+  // Error handler
+  router.use('/', commonErrorHandler);
+
+  return router;
+}
+
+module.exports = { createEntityRouter, isUuidV4 };
+```
+
+Generic CRUD query safety:
+
+- `PUT /:id` uses `req.params.id` as the canonical id and rejects mismatched
+  body ids.
+- List and count queries default to `limit=50`, max `limit=1000`, and sanitize
+  sort direction to `ASC` or `DESC`.
+- Sort fields are accepted only when present in the model's `rawAttributes` or
+  `DBApi.SORTABLE_FIELDS`.
+- CSV export uses the same auth path as list and is capped at `limit=1000`.
+- Autocomplete defaults to `limit=20` and is capped at `limit=50`.
+
+#### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `createEntityRouter` | `function` | Factory function |
+| `isUuidV4` | `function` | UUID validation helper |
+
+---
+
+### service.factory.ts
+
+**Purpose:** Generates service classes with standardized CRUD operations wrapped in database transactions.
+
+**Location:** `backend/src/factories/service.factory.ts`
+
+#### Function Signature
+
+```javascript
+function createEntityService(DBApi, options = {})
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `DBApi` | `class` | Database API class extending GenericDBApi |
+| `options` | `object` | Configuration options |
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `entityName` | `string` | `'Entity'` | Name used in error messages |
+
+#### Generated Methods
+
+| Method | Description |
+|--------|-------------|
+| `create({ data, currentUser, transaction, runtimeContext })` | Create record with transaction |
+| `bulkImport(req, res)` | Bulk import from CSV with transaction |
+| `update({ id, data, currentUser, transaction, runtimeContext })` | Update record with transaction |
+| `deleteByIds({ ids, currentUser, transaction, runtimeContext })` | Delete multiple with transaction |
+| `remove({ id, currentUser, transaction, runtimeContext })` | Delete single with transaction |
+
+#### Implementation
+
+```javascript
+const db = require('../db/models');
+const processFile = require('../middlewares/upload');
+const ValidationError = require('../services/notifications/errors/validation');
+const csv = require('csv-parser');
+const stream = require('stream');
+
+function createEntityService(DBApi, options = {}) {
+  const entityName = options.entityName || 'Entity';
+
+  return class GenericService {
+    static async create({ data, currentUser, transaction: externalTransaction, runtimeContext }) {
+      const transaction = externalTransaction || await db.sequelize.transaction();
+      const ownsTransaction = !externalTransaction;
+      try {
+        const record = await DBApi.create({ data, currentUser, transaction, runtimeContext });
+        if (ownsTransaction) await transaction.commit();
+        return record;
+      } catch (error) {
+        if (ownsTransaction) await transaction.rollback();
+        throw error;
+      }
+    }
+
+    static async bulkImport(req, res) {
+      const transaction = await db.sequelize.transaction();
+      try {
+        await processFile(req, res);
+        const bufferStream = new stream.PassThrough();
+        const results = [];
+
+        await bufferStream.end(Buffer.from(req.file.buffer, 'utf-8'));
+
+        await new Promise((resolve, reject) => {
+          bufferStream
+            .pipe(csv())
+            .on('data', (data) => results.push(data))
+            .on('end', () => resolve())
+            .on('error', (error) => reject(error));
+        });
+
+        await DBApi.bulkImport(results, {
+          transaction,
+          ignoreDuplicates: true,
+          validate: true,
+          currentUser: req.currentUser,
+        });
+
+        await transaction.commit();
+      } catch (error) {
+        await transaction.rollback();
+        throw error;
+      }
+    }
+
+    static async update({ id, data, currentUser, transaction: externalTransaction, runtimeContext }) {
+      const transaction = externalTransaction || await db.sequelize.transaction();
+      const ownsTransaction = !externalTransaction;
+      try {
+        const record = await DBApi.findBy({ id }, { transaction, runtimeContext });
+
+        if (!record) {
+          throw new ValidationError(`${entityName}NotFound`);
+        }
+
+        const updated = await DBApi.update({ id, data, currentUser, transaction, runtimeContext });
+        if (ownsTransaction) await transaction.commit();
+        return updated;
+      } catch (error) {
+        if (ownsTransaction) await transaction.rollback();
+        throw error;
+      }
+    }
+
+    static async deleteByIds({ ids, currentUser, transaction: externalTransaction, runtimeContext }) {
+      const transaction = externalTransaction || await db.sequelize.transaction();
+      const ownsTransaction = !externalTransaction;
+      try {
+        await DBApi.deleteByIds({ ids, currentUser, transaction, runtimeContext });
+        if (ownsTransaction) await transaction.commit();
+      } catch (error) {
+        if (ownsTransaction) await transaction.rollback();
+        throw error;
+      }
+    }
+
+    static async remove({ id, currentUser, transaction: externalTransaction, runtimeContext }) {
+      const transaction = externalTransaction || await db.sequelize.transaction();
+      const ownsTransaction = !externalTransaction;
+      try {
+        await DBApi.remove({ id, currentUser, transaction, runtimeContext });
+        if (ownsTransaction) await transaction.commit();
+      } catch (error) {
+        if (ownsTransaction) await transaction.rollback();
+        throw error;
+      }
+    }
+  };
+}
+
+module.exports = { createEntityService };
+```
+
+#### Transaction Pattern
+
+All service methods follow the same transaction pattern:
+
+```javascript
+static async methodName(params) {
+  const transaction = await db.sequelize.transaction();
+  try {
+    // ... database operations with { transaction }
+    await transaction.commit();
+    return result;
+  } catch (error) {
+    await transaction.rollback();
+    throw error;
+  }
+}
+```
+
+---
+
+## Supporting Components
+
+### helpers.js
+
+**Location:** `backend/src/helpers.js`
+
+Helper utilities used by the router factory:
+
+```javascript
+module.exports = class Helpers {
+  // Wrap async route handlers to propagate errors
+  static wrapAsync(fn) {
+    return function (req, res, next) {
+      fn(req, res, next).catch(next);
+    };
+  }
+
+  // Centralized error response handler
+  static commonErrorHandler(error, req, res, _next) {
+    const statusCode = error.code || error.status;
+
+    if ([400, 401, 403, 404, 409, 422].includes(statusCode)) {
+      return res.status(statusCode).send(error.message);
+    }
+
+    console.error(error);
+    return res.status(500).send('Internal server error');
+  }
+
+  // JWT token signing
+  static jwtSign(data) {
+    return jwt.sign(data, config.secret_key, { expiresIn: '6h' });
+  }
+
+  // UUID v4 validation
+  static isUuidV4(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+  }
+};
+```
+
+### check-permissions.ts
+
+**Location:** `backend/src/middlewares/check-permissions.ts`
+
+Permission checking middleware used by router factory:
+
+```javascript
+// HTTP method to permission action mapping
+const METHOD_MAP = {
+  POST: 'CREATE',
+  GET: 'READ',
+  PUT: 'UPDATE',
+  PATCH: 'UPDATE',
+  DELETE: 'DELETE',
+};
+
+// Entities accessible publicly in runtime mode
+const RUNTIME_PUBLIC_READ_ENTITIES = new Set([
+  'PROJECTS',
+  'TOUR_PAGES',
+  'PAGE_ELEMENTS',
+  'PAGE_LINKS',
+  'TRANSITIONS',
+  'PROJECT_AUDIO_TRACKS',
+]);
+
+// Generate permission name from HTTP method and entity
+function checkCrudPermissions(name) {
+  return (req, res, next) => {
+    // Skip auth for public runtime read requests
+    const isRuntimePublicRead =
+      req.isRuntimePublicRequest === true &&
+      req.method === 'GET' &&
+      RUNTIME_PUBLIC_READ_ENTITIES.has(name.toUpperCase());
+
+    if (isRuntimePublicRead) {
+      return next();
+    }
+
+    // Build permission name: e.g., 'READ_ASSETS', 'CREATE_USERS'
+    const permissionName = `${METHOD_MAP[req.method]}_${name.toUpperCase()}`;
+    return checkPermissions(permissionName)(req, res, next);
+  };
+}
+```
+
+---
+
+## GenericDBApi (Base Class)
+
+**Location:** `backend/src/db/api/base.api.ts`
+
+The DB API base class that all entity APIs extend. Provides declarative configuration for CRUD operations.
+
+### Static Getters (Override in Subclasses)
+
+| Getter | Type | Description |
+|--------|------|-------------|
+| `MODEL` | `Model` | Sequelize model reference (required) |
+| `TABLE_NAME` | `string` | Database table name |
+| `SEARCHABLE_FIELDS` | `string[]` | Fields for text search (ILIKE) |
+| `RANGE_FIELDS` | `string[]` | Fields for range filtering |
+| `ENUM_FIELDS` | `string[]` | Fields for exact match filtering |
+| `RELATION_FILTERS` | `object[]` | Related entity filters |
+| `CSV_FIELDS` | `string[]` | Fields for CSV export |
+| `AUTOCOMPLETE_FIELD` | `string` | Field for autocomplete |
+| `ASSOCIATIONS` | `object[]` | Related entity setters |
+| `FIND_BY_INCLUDES` | `object[]` | Includes for findBy |
+| `FIND_ALL_INCLUDES` | `object[]` | Includes for findAll |
+| `JSON_FIELDS` | `string[]` | Fields to auto-stringify |
+| `FIELD_TRANSFORMERS` | `object` | Custom field transformers |
+| `FIELD_DEFAULTS` | `object` | Default values for fields |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `getFieldMapping(data)` | Transform input data for database |
+| `create(data, options)` | Create record |
+| `bulkImport(data, options)` | Bulk create records |
+| `update({ id, data, currentUser, transaction, runtimeContext })` | Update record |
+| `deleteByIds({ ids, currentUser, transaction, runtimeContext })` | Soft delete multiple |
+| `remove({ id, currentUser, transaction, runtimeContext })` | Soft delete single |
+| `findBy(where, options)` | Find single by criteria |
+| `findAll(filter, options)` | Find all with pagination/filters |
+| `findAllAutocomplete({ query, limit, offset }, options)` | Autocomplete search |
+| `toCSV(rows)` | Convert to CSV string |
+
+---
+
+## Usage Examples
+
+### Basic Entity (Minimal Configuration)
+
+**Route (assets.ts):**
+```typescript
+import AssetsDBApi from '../db/api/assets.ts';
+import { createEntityRouter } from '../factories/router.factory.ts';
+import AssetsService from '../services/assets.ts';
+
+// 1 line: generates 9 CRUD endpoints
+export default createEntityRouter('assets', AssetsService, AssetsDBApi);
+```
+
+**Service (assets.ts):**
+```typescript
+import AssetsDBApi from '../db/api/assets.ts';
+import { createEntityService } from '../factories/service.factory.ts';
+
+// 1 line: generates service class with 5 transaction-wrapped methods
+export default createEntityService(AssetsDBApi, {
+  entityName: 'assets',
+});
+```
+
+**DB API (assets.js):**
+```javascript
+const GenericDBApi = require('./base.api');
+const db = require('../models');
+
+class AssetsDBApi extends GenericDBApi {
+  static get MODEL() {
+    return db.assets;
+  }
+
+  static get SEARCHABLE_FIELDS() {
+    return ['name', 'cdn_url', 'storage_key', 'mime_type', 'checksum'];
+  }
+
+  static get RANGE_FIELDS() {
+    return ['size_mb', 'width_px', 'height_px', 'duration_sec'];
+  }
+
+  static get ENUM_FIELDS() {
+    return ['asset_type', 'type', 'is_public'];
+  }
+
+  static get ASSOCIATIONS() {
+    return [{ field: 'project', setter: 'setProject', isArray: false }];
+  }
+
+  static getFieldMapping(data) {
+    return {
+      name: data.name || null,
+      asset_type: data.asset_type || null,
+      type: data.type || 'general',
+      cdn_url: data.cdn_url || null,
+      // ... other fields
+    };
+  }
+}
+
+module.exports = AssetsDBApi;
+```
+
+### Entity with Custom Routes
+
+**Route (project_element_defaults.ts):**
+```typescript
+import Service from '../services/project_element_defaults.ts';
+import DBApi from '../db/api/project_element_defaults.ts';
+import { createEntityRouter } from '../factories/router.factory.ts';
+import { wrapAsync } from '../helpers.ts';
+
+// Create base router
+const baseRouter = createEntityRouter(
+  'project_element_defaults',
+  Service,
+  DBApi,
+  { permissionEntity: 'page_elements' }  // Override permission entity
+);
+
+// Add custom endpoint
+baseRouter.post('/:id/reset', wrapAsync(async (req, res) => {
+  const payload = await Service.resetToGlobal(req.params.id, {
+    currentUser: req.currentUser,
+  });
+  res.status(200).json(payload);
+}));
+
+// Add another custom endpoint
+baseRouter.get('/:id/diff', wrapAsync(async (req, res) => {
+  const payload = await Service.getDiffFromGlobal(req.params.id);
+  res.status(200).json(payload);
+}));
+
+export default baseRouter;
+```
+
+### Service with Extended Methods
+
+**Service (project_element_defaults.ts):**
+```typescript
+import DBApi from '../db/api/project_element_defaults.ts';
+import { createEntityService } from '../factories/service.factory.ts';
+
+// Create base service class
+const BaseService = createEntityService(DBApi, {
+  entityName: 'project_element_defaults',
+});
+
+// Extend with custom methods
+export default class Project_element_defaultsService extends BaseService {
+  static resetToGlobal(id, options = {}) {
+    return DBApi.resetToGlobal(id, options);
+  }
+
+  static getDiffFromGlobal(id) {
+    return DBApi.getDiffFromGlobal(id);
+  }
+
+  static snapshotGlobalDefaults(projectId, options = {}) {
+    return DBApi.snapshotGlobalDefaults(projectId, options);
+  }
+}
+```
+
+### Using customRoutes Callback
+
+Alternative approach using the options callback:
+
+```javascript
+module.exports = createEntityRouter('entities', Service, DBApi, {
+  customRoutes: (router, Service, DBApi) => {
+    router.post('/:id/custom-action', wrapAsync(async (req, res) => {
+      const result = await Service.customAction(req.params.id);
+      res.status(200).json(result);
+    }));
+
+    router.get('/stats', wrapAsync(async (req, res) => {
+      const stats = await DBApi.getStatistics();
+      res.status(200).json(stats);
+    }));
+  }
+});
+```
+
+---
+
+## Entity Usage Summary
+
+### Entities Using Router Factory (13)
+
+| Entity | Permission Override | Custom Routes |
+|--------|--------------------|--------------|
+| `access_logs` | - | No |
+| `asset_variants` | - | No |
+| `assets` | - | No |
+| `element_type_defaults` | - | No |
+| `permissions` | - | No |
+| `presigned_url_requests` | - | No |
+| `project_audio_tracks` | - | No |
+| `project_element_defaults` | `page_elements` | Yes (reset, diff) |
+| `project_memberships` | - | No |
+| `publish_events` | - | No |
+| `pwa_caches` | - | No |
+| `roles` | - | No |
+| `tour_pages` | - | No |
+
+### Entities Using Service Factory (11)
+
+| Entity | Custom Methods |
+|--------|---------------|
+| `access_logs` | No |
+| `asset_variants` | No |
+| `assets` | No |
+| `element_type_defaults` | No |
+| `permissions` | No |
+| `presigned_url_requests` | No |
+| `pwa_caches` | No |
+| `publish_events` | No |
+| `tour_pages` | No |
+| `project_element_defaults` | Yes (resetToGlobal, getDiffFromGlobal, snapshotGlobalDefaults) |
+| `project_memberships` | No |
+
+### Entities NOT Using Factories
+
+Some entities have custom implementations due to specialized requirements:
+
+| Entity | Reason |
+|--------|--------|
+| `users` | Complex auth, password hashing, token management |
+| `projects` | Publishing workflow, complex business logic |
+| `auth` | Authentication flows (login, OAuth, password reset) |
+| `file` | File upload/download, S3/GCloud/Local storage |
+| `search` | Full-text search across multiple entities |
+| `publish` | Multi-step publishing workflow |
+
+---
+
+## Generated Endpoints Flow
+
+```
+HTTP Request
+    │
+    ▼
+┌─────────────────────────────────┐
+│ JWT Authentication              │  (from index.js)
+│ passport.authenticate('jwt')    │
+└─────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────┐
+│ checkCrudPermissions()          │  (from router.factory.ts)
+│ - Maps HTTP method to action    │
+│ - Builds permission name        │
+│ - Checks user role permissions  │
+└─────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────┐
+│ Route Handler                   │  (from router.factory.ts)
+│ - wrapAsync() for error catch   │
+│ - Calls Service method          │
+└─────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────┐
+│ Service Method                  │  (from service.factory.ts)
+│ - Starts transaction            │
+│ - Calls DBApi method            │
+│ - Commits or rollbacks          │
+└─────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────┐
+│ DBApi Method                    │  (from base.api.ts + entity)
+│ - getFieldMapping() transform   │
+│ - Sequelize model operation     │
+│ - Returns result                │
+└─────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────┐
+│ commonErrorHandler()            │  (from helpers.js)
+│ - Formats error response        │
+│ - Appropriate HTTP status       │
+└─────────────────────────────────┘
+    │
+    ▼
+HTTP Response
+```
+
+---
+
+## Design Patterns
+
+### Factory Pattern
+Both `createEntityRouter` and `createEntityService` implement the Factory pattern, creating objects (router, service class) without specifying their exact classes.
+
+### Template Method Pattern
+`GenericDBApi.getFieldMapping()` uses the Template Method pattern - the base class defines the algorithm skeleton, while subclasses can override specific steps via static getters (`JSON_FIELDS`, `FIELD_TRANSFORMERS`, `FIELD_DEFAULTS`).
+
+### Strategy Pattern
+The permission checking system uses Strategy pattern - different entities can have different permission strategies by overriding `permissionEntity` option.
+
+### Decorator Pattern
+The router factory decorates Express routers with permission middleware and error handling.
+
+---
+
+## Best Practices
+
+### When to Use Factories
+
+Use factories when:
+- Entity requires standard CRUD operations
+- No complex business logic beyond data transformation
+- Permissions follow standard READ/CREATE/UPDATE/DELETE pattern
+- No special authentication requirements
+
+### When NOT to Use Factories
+
+Don't use factories when:
+- Complex multi-step workflows (use custom service)
+- Special authentication (OAuth flows, password reset)
+- External API integration (file storage, AI)
+- Cross-entity transactions
+- Custom endpoint patterns
+
+### Extending Factory-Generated Code
+
+1. **Add custom routes:** Extend the base router after factory call
+2. **Add custom service methods:** Extend the generated class
+3. **Override permissions:** Use `permissionEntity` option
+4. **Customize data transformation:** Override `getFieldMapping()` in DBApi
+
+---
+
+## Related Documentation
+
+- [Services Module](./services.md) - Business logic layer
+- [Routes Module](./routes.md) - All route files
+- [Middleware Module](./middleware.md) - Permission checking
+- [Database Schema](../database-schema.md) - Model definitions
diff --git a/backend/docs/modules/middleware.md b/backend/docs/modules/middleware.md
new file mode 100644
index 0000000..858520b
--- /dev/null
+++ b/backend/docs/modules/middleware.md
@@ -0,0 +1,842 @@
+# Backend Middleware Module Documentation
+
+## Overview
+
+The Middleware module provides cross-cutting concerns for the Express application including rate limiting, permission checking, runtime context management, file uploads, and public access control.
+
+**Files:**
+| File | Lines | Purpose |
+|------|-------|---------|
+| `src/middlewares/rateLimiter.js` | 268 | Configurable rate limiting with in-memory store |
+| `src/middlewares/check-permissions.ts` | RBAC permission checking through AccessPolicy |
+| `src/middlewares/runtime-context.ts` | 34 | Runtime environment context from headers |
+| `src/middlewares/runtime-public.ts` | 200 | Public runtime access control and response sanitization |
+| `src/middlewares/upload.ts` | 34 | Multer-based file upload handling |
+
+---
+
+## Architecture Diagram
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                         Incoming Request                             │
+└──────────────────────────────────┬───────────────────────────────────┘
+                                   │
+                                   ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                    Express Middleware Stack                          │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 1. helmet() - Security headers                                 │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 2. cors() - Cross-origin resource sharing                     │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 3. requestLogger - Pino HTTP logging                          │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 4. Rate Limiters (route-specific)                             │  │
+│  │    • downloadLimiter → /api/file/download, /api/file/presign  │  │
+│  │    • uploadLimiter → /api/file/upload                         │  │
+│  │    • searchLimiter → /api/search                              │  │
+│  │    • authLimiter → /api/auth/signin                           │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 5. bodyParser.json() - JSON body parsing (after file routes)  │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 6. runtimeContextMiddleware - Environment context             │  │
+│  │    Reads: X-Runtime-Environment, X-Runtime-Project-Slug       │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 7. JWT Authentication (route-specific)                        │  │
+│  │    passport.authenticate('jwt', { session: false })           │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 8. Runtime Public Middleware (route-specific)                 │  │
+│  │    • blockNonPublicRuntimeListEndpoints                       │  │
+│  │    • sanitizePublicRuntimeListResponse                        │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 9. checkCrudPermissions / checkPermissions (route-specific)   │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 10. Route Handler                                             │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+│                                   │                                  │
+│                                   ▼                                  │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │ 11. Error Handler (commonErrorHandler)                        │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## File Details
+
+### 1. rateLimiter.js (268 lines)
+
+In-memory rate limiting middleware with configurable windows and limits.
+
+#### Storage Architecture
+
+```javascript
+// In-memory store (Map)
+const rateLimitStore = new Map();
+
+// Entry structure
+{
+  count: number,      // Request count in window
+  expiresAt: number,  // Window expiration timestamp
+  resetTime: string   // ISO timestamp for headers
+}
+
+// Automatic cleanup every 5 minutes
+setInterval(() => {
+  for (const [key, entry] of rateLimitStore.entries()) {
+    if (entry.expiresAt <= now) {
+      rateLimitStore.delete(key);
+    }
+  }
+}, 5 * 60 * 1000);
+```
+
+#### Factory: createRateLimiter(options)
+
+Creates a configurable rate limiter middleware.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `keyPrefix` | string | `'rate-limit'` | Prefix for rate limit keys |
+| `windowMs` | number | `900000` (15min) | Time window in milliseconds |
+| `max` | number | `100` | Maximum requests per window |
+| `message` | string | `'Too many requests...'` | Error message on limit |
+| `skipFailedRequests` | boolean | `false` | Don't count 4xx/5xx responses |
+| `keyGenerator` | function | `null` | Custom key generator `(req) => string` |
+| `skip` | function | `null` | Skip rate limiting `(req) => boolean` |
+
+**Returns:** Express middleware function
+
+**Response Headers:**
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 99
+X-RateLimit-Reset: 2024-01-01T00:15:00.000Z
+Retry-After: 300  (only when limit exceeded)
+```
+
+**Rate Limit Exceeded Response (429):**
+```json
+{
+  "error": "Too Many Requests",
+  "message": "Too many requests. Please try again later.",
+  "retryAfter": 300
+}
+```
+
+#### Factory: createAuthenticatedRateLimiter(options)
+
+Creates rate limiter that uses IP + User ID as key.
+
+```javascript
+const createAuthenticatedRateLimiter = (options = {}) => {
+  return createRateLimiter({
+    ...options,
+    keyGenerator: (req) => {
+      const userId = req.currentUser?.id || 'anonymous';
+      const ip = req.ip || 'unknown';
+      return `${ip}:${userId}`;
+    },
+  });
+};
+```
+
+#### Pre-configured Limiters
+
+| Limiter | Key Prefix | Window | Max | Skip Failed | Use Case |
+|---------|------------|--------|-----|-------------|----------|
+| `authLimiter` | `auth` | 15 min | 10 | No | Login attempts |
+| `passwordResetLimiter` | `password-reset` | 1 hour | 5 | No | Password reset |
+| `apiLimiter` | `api` | 1 min | 100 | Yes | General API |
+| `uploadLimiter` | `upload` | 1 min | 10 | No | File uploads |
+| `downloadLimiter` | `download` | 1 min | 200 | Yes | File downloads |
+| `searchLimiter` | `search` | 1 min | 30 | No | Search queries |
+
+#### Route Mapping
+
+```javascript
+// index.js
+app.use('/api/file/download', downloadLimiter);
+app.use('/api/file/presign', downloadLimiter);
+app.use('/api/file/upload', uploadLimiter);
+app.use('/api/file/upload-sessions', uploadLimiter);
+app.use('/api/search', jwtAuth, searchLimiter, searchRoutes);
+
+// routes/auth.js
+router.post('/signin/local', signinLimiter, handler);
+router.post('/send-password-reset-email', passwordResetLimiter, handler);
+```
+
+#### Development Mode
+
+Rate limiting is skipped for localhost in development:
+
+```javascript
+if (
+  config.server.env === 'development' &&
+  (req.ip === '127.0.0.1' || req.ip === '::1')
+) {
+  return next(); // Skip rate limiting
+}
+```
+
+---
+
+### 2. check-permissions.ts (194 lines)
+
+Role-based access control (RBAC) middleware. Permission decisions are delegated
+to `src/services/access-policy.ts` so role/custom permission resolution and
+Public-user hardening stay centralized.
+
+#### Public Role Caching
+
+```javascript
+let publicRoleCache = null;
+
+// Fetched on module load (startup)
+async function fetchAndCachePublicRole() {
+  publicRoleCache = await RolesDBApi.findBy({ name: 'Public' });
+}
+
+// Called immediately when module is imported
+fetchAndCachePublicRole();
+```
+
+#### Function: checkPermissions(permission)
+
+Creates middleware that checks if user has specific permission.
+
+**Permission Check Flow:**
+```
+1. AccessPolicy.hasPermission(user, permission)
+   ├── Public users are always denied admin API permissions
+   └── Internal users use app_role.permissions + custom_permissions
+
+2. Public role fallback
+   └── Unauthenticated/no-role requests use cached Public role, but Public role permissions are ignored
+
+3. Role lacks permission → 403 Forbidden
+```
+
+Self-access bypass is not part of `checkPermissions`. It is explicitly limited
+to `GET`, `PUT`, and `PATCH` on the authenticated user's own `/api/users/:id`
+route in `checkCrudPermissions`.
+
+**Usage:**
+```javascript
+const { checkPermissions } = require('./middlewares/check-permissions');
+
+// Check specific permission
+router.get('/admin', checkPermissions('ADMIN_ACCESS'), handler);
+
+// Check entity permission
+router.get('/users', checkPermissions('READ_USERS'), handler);
+```
+
+**Error Response (403):**
+```json
+{
+  "message": "Forbidden"
+}
+```
+
+#### Function: checkCrudPermissions(name)
+
+Creates middleware that maps HTTP method to CRUD permission.
+
+**Method Mapping:**
+| HTTP Method | Permission Prefix |
+|-------------|-------------------|
+| `POST` | `CREATE_` |
+| `GET` | `READ_` |
+| `PUT` | `UPDATE_` |
+| `PATCH` | `UPDATE_` |
+| `DELETE` | `DELETE_` |
+
+**Permission Name Format:** `{METHOD}_{ENTITY}`
+
+Examples:
+- `GET /api/users` → `READ_USERS`
+- `POST /api/projects` → `CREATE_PROJECTS`
+- `DELETE /api/assets/123` → `DELETE_ASSETS`
+
+Routes can set `req.permissionNameOverride` before `checkCrudPermissions` when
+the HTTP verb does not describe the domain operation. The middleware uses the
+override as the exact permission name and otherwise falls back to
+`{METHOD}_{ENTITY}`. For example, environment-level resets for project runtime
+settings use `DELETE` to remove an override row, but the user-facing operation
+is "use inherited defaults", so those routes require `UPDATE_PAGE_ELEMENTS`
+rather than `DELETE_PAGE_ELEMENTS`.
+
+**Usage:**
+```javascript
+const { checkCrudPermissions } = require('./middlewares/check-permissions');
+
+// In router factory
+router.get('/', checkCrudPermissions('users'), listHandler);
+router.post('/', checkCrudPermissions('users'), createHandler);
+router.delete('/:id', checkCrudPermissions('users'), deleteHandler);
+
+// For reset/update semantics implemented as DELETE
+router.use((req, _res, next) => {
+  if (req.method === 'DELETE' && req.path.startsWith('/project/')) {
+    req.permissionNameOverride = 'UPDATE_PAGE_ELEMENTS';
+  }
+  next();
+});
+router.use(checkCrudPermissions('page_elements'));
+```
+
+#### Runtime Public Read Bypass
+
+Certain entities allow public read access in production runtime:
+
+```javascript
+const RUNTIME_PUBLIC_READ_ENTITIES = new Set([
+  'PROJECTS',
+  'TOUR_PAGES',
+  'PAGE_ELEMENTS',
+  'PAGE_LINKS',
+  'TRANSITIONS',
+  'PROJECT_AUDIO_TRACKS',
+  'GLOBAL_TRANSITION_DEFAULTS',
+  'PROJECT_TRANSITION_SETTINGS',
+]);
+
+// Bypass permission check for public runtime reads
+const isRuntimePublicRead =
+  req.isRuntimePublicRequest === true &&
+  req.method === 'GET' &&
+  RUNTIME_PUBLIC_READ_ENTITIES.has(name.toUpperCase());
+
+if (isRuntimePublicRead) {
+  return next(); // Skip permission check
+}
+```
+
+**⚠️ Middleware Ordering Requirement:**
+
+For public read bypass to work, the middleware that sets `req.isRuntimePublicRequest = true` **MUST run before** `checkCrudPermissions`. Common mistake:
+
+```javascript
+// ❌ WRONG - allowPublicRead runs AFTER checkCrudPermissions
+router.use(checkCrudPermissions('entity'));
+router.get('/', allowPublicRead, handler);  // Too late!
+
+// ✅ CORRECT - allowPublicRead runs BEFORE checkCrudPermissions
+router.use(allowPublicRead);
+router.use(checkCrudPermissions('entity'));
+router.get('/', handler);
+```
+
+When using `router.use()`, middleware is applied to ALL routes before route-specific middleware runs.
+
+---
+
+### 3. runtime-context.ts (34 lines)
+
+Middleware that extracts runtime environment context from request headers.
+
+#### Function: runtimeContextMiddleware
+
+Reads environment and project slug from headers for route-based access.
+
+**Headers:**
+| Header | Values | Description |
+|--------|--------|-------------|
+| `X-Runtime-Environment` | `production`, `stage`, `dev` | Content environment |
+| `X-Runtime-Project-Slug` | string | Project identifier |
+
+**Context Object:**
+```javascript
+req.runtimeContext = {
+  mode: 'admin',              // Default mode
+  projectSlug: null,          // Extracted from path or header
+  headerEnvironment: 'production',  // From X-Runtime-Environment
+  headerProjectSlug: 'my-tour'      // From X-Runtime-Project-Slug
+};
+```
+
+**Usage in Routes:**
+```javascript
+// index.js
+app.use(runtimeContextMiddleware);
+
+// Access in handlers
+const env = req.runtimeContext?.headerEnvironment;
+if (env === 'production') {
+  // Filter for production content
+}
+```
+
+**Route-Based Environment Access:**
+| Route | Environment | Access |
+|-------|-------------|--------|
+| `/p/[slug]` | `production` | Public (no auth) |
+| `/p/[slug]/stage` | `stage` | Authenticated only |
+| `/constructor?projectId=` | `dev` | Authenticated only |
+
+---
+
+### 4. runtime-public.ts (200 lines)
+
+Middleware for controlling public runtime access and sanitizing responses.
+
+#### Allowed Fields (Whitelist)
+
+Only these fields are returned for public runtime requests:
+
+```javascript
+const PUBLIC_RUNTIME_ENTITY_FIELDS = {
+  projects: [
+    'id', 'name', 'slug', 'description', 'logo_url', 'favicon_url', 'og_image_url',
+  ],
+  tour_pages: [
+    'id', 'projectId', 'environment', 'source_key', 'name', 'slug',
+    'sort_order', 'background_image_url', 'background_video_url',
+    'background_audio_url', 'background_loop', 'requires_auth', 'ui_schema_json',
+  ],
+  project_audio_tracks: [
+    'id', 'projectId', 'environment', 'source_key', 'name', 'slug',
+    'url', 'loop', 'volume', 'sort_order', 'is_enabled',
+  ],
+};
+```
+
+#### Function: blockNonPublicRuntimeListEndpoints
+
+Restricts public runtime requests to list endpoints only.
+
+```javascript
+const blockNonPublicRuntimeListEndpoints = (req, res, next) => {
+  if (!isPublicRuntimeReadRequest(req)) {
+    return next(); // Not a public request, continue
+  }
+
+  // Only allow root path (list endpoint)
+  if (req.path !== '/') {
+    return res.status(404).send({ message: 'Not found' });
+  }
+
+  // Block CSV exports
+  if (req.query.filetype === 'csv') {
+    return res.status(404).send({ message: 'Not found' });
+  }
+
+  return next();
+};
+```
+
+**Blocked:**
+- Individual record access: `GET /api/projects/123` → 404
+- CSV exports: `GET /api/projects?filetype=csv` → 404
+
+**Allowed:**
+- List endpoints: `GET /api/projects/` → Continue
+
+#### Function: sanitizePublicRuntimeListResponse(entityName)
+
+Filters response data to only include whitelisted fields.
+
+```javascript
+const sanitizePublicRuntimeListResponse = (entityName) => {
+  const fields = PUBLIC_RUNTIME_ENTITY_FIELDS[entityName] || [];
+
+  return (req, res, next) => {
+    // Intercept res.send()
+    const originalSend = res.send.bind(res);
+
+    res.send = (body) => {
+      if (Array.isArray(body.rows)) {
+        const sanitizedRows = body.rows.map((row) => pickFields(row, fields));
+        return originalSend({ ...body, rows: sanitizedRows });
+      }
+      return originalSend(body);
+    };
+
+    return next();
+  };
+};
+```
+
+**Before Sanitization:**
+```json
+{
+  "rows": [{
+    "id": "123",
+    "name": "My Tour",
+    "slug": "my-tour",
+    "createdAt": "2024-01-01",
+    "createdById": "user-456",
+    "internalNotes": "sensitive data"
+  }]
+}
+```
+
+**After Sanitization:**
+```json
+{
+  "rows": [{
+    "id": "123",
+    "name": "My Tour",
+    "slug": "my-tour"
+  }]
+}
+```
+
+#### Usage in index.js
+
+```javascript
+const mountRuntimeEntityRoute = (path, entityName, router) => {
+  app.use(
+    path,
+    requireRuntimeReadOrAuth,           // JWT or public access
+    blockNonPublicRuntimeListEndpoints, // Block non-list endpoints
+    sanitizePublicRuntimeListResponse(entityName), // Filter fields
+    router,
+  );
+};
+
+mountRuntimeEntityRoute('/api/projects', 'projects', projectsRoutes);
+mountRuntimeEntityRoute('/api/tour_pages', 'tour_pages', tour_pagesRoutes);
+mountRuntimeEntityRoute('/api/project_audio_tracks', 'project_audio_tracks', ...);
+```
+
+---
+
+### 5. upload.ts (34 lines)
+
+Simple Multer-based file upload middleware.
+
+```javascript
+const util = require('util');
+const Multer = require('multer');
+
+let processFile = Multer({
+  storage: Multer.memoryStorage(),
+}).single('file');
+
+let processFileMiddleware = util.promisify(processFile);
+module.exports = processFileMiddleware;
+```
+
+**Configuration:**
+| Setting | Value |
+|---------|-------|
+| Storage | Memory (Buffer) |
+| Field Name | `file` |
+| Max Files | 1 (single) |
+
+**Usage:**
+```javascript
+const upload = require('./middlewares/upload');
+
+router.post('/upload', async (req, res) => {
+  await upload(req, res);
+  // req.file contains:
+  // - buffer: File data
+  // - originalname: Original filename
+  // - mimetype: MIME type
+  // - size: File size in bytes
+});
+```
+
+**Note:** This middleware is primarily used for legacy uploads. The main file upload system uses chunked uploads without this middleware.
+
+---
+
+## Middleware Composition Patterns
+
+### Pattern 1: Route-Level Rate Limiting
+
+```javascript
+// Apply limiter before route handler
+app.use('/api/file/upload', uploadLimiter);
+app.use('/api/file', fileRoutes);
+```
+
+### Pattern 2: Inline Middleware Chain
+
+```javascript
+// Multiple middlewares in route definition
+router.post(
+  '/signin/local',
+  signinLimiter,           // Rate limit
+  wrapAsync(async (req, res) => { ... }),
+);
+```
+
+### Pattern 3: JWT + Feature Middleware
+
+```javascript
+// JWT auth + rate limit + routes
+app.use('/api/search', jwtAuth, searchLimiter, searchRoutes);
+```
+
+### Pattern 4: Conditional Auth (Runtime)
+
+```javascript
+const requireRuntimeReadOrAuth = (req, res, next) => {
+  const headerEnvironment = req.runtimeContext?.headerEnvironment;
+  const isReadOnlyRequest = ['GET', 'OPTIONS'].includes(req.method);
+  const hasAuthHeader = Boolean(req.headers.authorization);
+  const isPublicEnvironment = headerEnvironment === 'production';
+
+  if (isPublicEnvironment && isReadOnlyRequest && !hasAuthHeader) {
+    req.isRuntimePublicRequest = true;
+    return next(); // Allow without auth
+  }
+
+  req.isRuntimePublicRequest = false;
+  return jwtAuth(req, res, next); // Require auth
+};
+```
+
+### Pattern 5: Response Interception
+
+```javascript
+// Intercept and modify response before sending
+const sanitizeResponse = (req, res, next) => {
+  const originalSend = res.send.bind(res);
+
+  res.send = (body) => {
+    const modified = transformBody(body);
+    return originalSend(modified);
+  };
+
+  return next();
+};
+```
+
+---
+
+## Request Flow Examples
+
+### Example 1: Authenticated API Request
+
+```
+GET /api/users
+Authorization: Bearer <jwt>
+
+1. helmet() → Security headers
+2. cors() → CORS headers
+3. requestLogger → Log request
+4. bodyParser.json() → Parse body
+5. runtimeContextMiddleware → Set req.runtimeContext
+6. jwtAuth → Validate JWT, set req.currentUser
+7. checkCrudPermissions('users') → Check READ_USERS permission
+8. Route handler → Return users
+```
+
+### Example 2: Public Runtime Request
+
+```
+GET /api/projects
+X-Runtime-Environment: production
+
+1. helmet() → Security headers
+2. cors() → CORS headers
+3. requestLogger → Log request
+4. bodyParser.json() → Parse body
+5. runtimeContextMiddleware → Set req.runtimeContext.headerEnvironment = 'production'
+6. requireRuntimeReadOrAuth → Set req.isRuntimePublicRequest = true, skip JWT
+7. blockNonPublicRuntimeListEndpoints → Allow (path is '/')
+8. sanitizePublicRuntimeListResponse('projects') → Filter response fields
+9. checkCrudPermissions('projects') → Skip (isRuntimePublicRequest)
+10. Route handler → Return sanitized projects
+```
+
+### Example 3: Rate Limited Upload
+
+```
+POST /api/file/upload
+Authorization: Bearer <jwt>
+Content-Type: multipart/form-data
+
+1. uploadLimiter → Check rate limit (10/min)
+   ├── Under limit → Continue
+   └── Over limit → 429 Too Many Requests
+2. fileRoutes handles request (own body parsing)
+```
+
+---
+
+## Error Handling
+
+### Rate Limit Errors
+
+```javascript
+// 429 Too Many Requests
+{
+  "error": "Too Many Requests",
+  "message": "Too many requests. Please try again later.",
+  "retryAfter": 300
+}
+```
+
+### Permission Errors
+
+```javascript
+// 403 Forbidden (via ValidationError)
+{
+  "message": "Role 'User' denied access to 'DELETE_USERS'."
+}
+```
+
+### Public Access Errors
+
+```javascript
+// 404 Not Found (blocked endpoint)
+{
+  "message": "Not found"
+}
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Affects | Description |
+|----------|---------|-------------|
+| `NODE_ENV` | Rate limiting | Skip localhost in development |
+
+### Constants
+
+```javascript
+// rateLimiter.js
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+// check-permissions.ts
+const METHOD_MAP = {
+  POST: 'CREATE',
+  GET: 'READ',
+  PUT: 'UPDATE',
+  PATCH: 'UPDATE',
+  DELETE: 'DELETE',
+};
+
+const RUNTIME_PUBLIC_READ_ENTITIES = new Set([
+  'PROJECTS', 'TOUR_PAGES', 'PAGE_ELEMENTS',
+  'PAGE_LINKS', 'TRANSITIONS', 'PROJECT_AUDIO_TRACKS',
+]);
+
+// runtime-public.ts
+const PUBLIC_RUNTIME_ALLOWED_PATH = '/';
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `multer` | ^1.4.5 | Multipart form data parsing |
+| `util` | built-in | Promisify multer |
+
+**Internal Dependencies:**
+- `../utils/logger` - Pino logger for rate limit logging
+- `../services/notifications/errors/validation` - ValidationError class
+- `../db/api/roles` - RolesDBApi for Public role
+
+---
+
+## Security Considerations
+
+1. **Rate Limiting:** Prevents brute force and DoS attacks
+2. **Permission Checking:** RBAC with role hierarchy
+3. **Public Role Fallback:** Unauthenticated users get minimal permissions
+4. **Response Sanitization:** Prevents data leakage in public runtime
+5. **Self-Access Bypass:** Users can always access their own resources
+6. **Memory Store:** Not suitable for horizontal scaling (use Redis)
+
+---
+
+## Testing
+
+### Test Rate Limiting
+
+```bash
+# Should succeed (under limit)
+for i in {1..10}; do
+  curl -X POST http://localhost:3000/api/auth/signin/local \
+    -H "Content-Type: application/json" \
+    -d '{"email": "test@test.com", "password": "wrong"}'
+done
+
+# Should return 429 (over limit)
+curl -X POST http://localhost:3000/api/auth/signin/local \
+  -H "Content-Type: application/json" \
+  -d '{"email": "test@test.com", "password": "wrong"}'
+```
+
+### Test Public Runtime Access
+
+```bash
+# Should return sanitized projects
+curl http://localhost:3000/api/projects \
+  -H "X-Runtime-Environment: production"
+
+# Should return 404 (individual record blocked)
+curl http://localhost:3000/api/projects/123 \
+  -H "X-Runtime-Environment: production"
+```
+
+### Test Permission Check
+
+```bash
+# Should return 403 if user lacks permission
+curl http://localhost:3000/api/users \
+  -H "Authorization: Bearer <limited_user_jwt>"
+```
+
+---
+
+## Summary
+
+The Middleware module provides:
+
+1. **rateLimiter.js** - 8 pre-configured rate limiters with in-memory store
+2. **check-permissions.ts** - RBAC through AccessPolicy with user-route-only self access
+3. **runtime-context.ts** - Runtime environment context from headers
+4. **runtime-public.ts** - Public access control and response sanitization
+5. **upload.ts** - Simple Multer-based file upload
+
+**Key Features:**
+- Configurable rate limiting per endpoint type
+- Role-based permission checking with method-to-CRUD mapping
+- Public runtime access for production presentations
+- Response field filtering for public access
+- Memory-based storage (scales vertically, needs Redis for horizontal)
diff --git a/backend/docs/modules/notifications.md b/backend/docs/modules/notifications.md
new file mode 100644
index 0000000..e696775
--- /dev/null
+++ b/backend/docs/modules/notifications.md
@@ -0,0 +1,801 @@
+# Backend Notifications Module
+
+## Overview
+
+The Notifications module provides a centralized **error handling system** and **internationalization (i18n) catalog** for the backend. It includes custom error classes with HTTP status codes and a message resolution system that supports parameter substitution.
+
+**Location:** `backend/src/services/notifications/`
+
+**Total Files:** 4
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Services Layer                               │
+│  (auth.js, users.js, projects.js, roles.js, search.js, etc.)        │
+│                                                                     │
+│    throw new ValidationError('auth.userNotFound');                  │
+│    throw new ForbiddenError('auth.forbidden');                      │
+└───────────────────────────────┬─────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     Notifications Module                            │
+│                                                                     │
+│  ┌─────────────────────────────────────────────────────────────┐    │
+│  │                     Error Classes                           │    │
+│  │                     (errors/)                               │    │
+│  │  ┌─────────────────────┐  ┌─────────────────────┐           │    │
+│  │  │   ValidationError   │  │   ForbiddenError    │           │    │
+│  │  │   (HTTP 400)        │  │   (HTTP 403)        │           │    │
+│  │  └──────────┬──────────┘  └──────────┬──────────┘           │    │
+│  │             │                        │                      │    │
+│  │             └────────────┬───────────┘                      │    │
+│  │                          │                                  │    │
+│  │                          ▼                                  │    │
+│  │             ┌─────────────────────────┐                     │    │
+│  │             │     helpers.js          │                     │    │
+│  │             │  • getNotification()    │                     │    │
+│  │             │  • isNotification()     │                     │    │
+│  │             └────────────┬────────────┘                     │    │
+│  │                          │                                  │    │
+│  │                          ▼                                  │    │
+│  │             ┌─────────────────────────┐                     │    │
+│  │             │       list.js           │                     │    │
+│  │             │  (Message Catalog)      │                     │    │
+│  │             │  • auth.*               │                     │    │
+│  │             │  • iam.*                │                     │    │
+│  │             │  • importer.*           │                     │    │
+│  │             │  • errors.*             │                     │    │
+│  │             │  • emails.*             │                     │    │
+│  │             └─────────────────────────┘                     │    │
+│  └─────────────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      Error Handler Middleware                       │
+│                      (Generic error handling in index.js)           │
+│                                                                     │
+│   app.use((err, req, res, _next) => {                               │
+│     res.status(err.code || 500).json({ message: err.message });     │
+│   });                                                               │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Directory Structure
+
+```
+services/notifications/
+├── helpers.js           # Message resolution functions (31 LOC)
+├── list.js              # Message catalog / i18n strings (101 LOC)
+└── errors/
+    ├── validation.js    # ValidationError class - 400 (17 LOC)
+    └── forbidden.js     # ForbiddenError class - 403 (17 LOC)
+```
+
+---
+
+## Core Components
+
+### Message Catalog (`list.js`)
+
+Centralized storage for all user-facing messages and email content.
+
+```javascript
+const errors = {
+  app: {
+    title: 'Tour Builder Platform',
+  },
+
+  auth: {
+    userDisabled: 'Your account is disabled',
+    forbidden: 'Forbidden',
+    unauthorized: 'Unauthorized',
+    userNotFound: "Sorry, we don't recognize your credentials",
+    wrongPassword: "Sorry, we don't recognize your credentials",
+    weakPassword: 'This password is too weak',
+    emailAlreadyInUse: 'Email is already in use',
+    invalidEmail: 'Please provide a valid email',
+    passwordReset: {
+      invalidToken: 'Password reset link is invalid or has expired',
+      error: 'Email not recognized',
+    },
+    passwordUpdate: {
+      samePassword: "You can't use the same password. Please create new password",
+    },
+    userNotVerified: 'Sorry, your email has not been verified yet',
+    emailAddressVerificationEmail: {
+      invalidToken: 'Email verification link is invalid or has expired',
+      error: 'Email not recognized',
+    },
+  },
+
+  iam: {
+    errors: {
+      userAlreadyExists: 'User with this email already exists',
+      userNotFound: 'User not found',
+      disablingHimself: "You can't disable yourself",
+      revokingOwnPermission: "You can't revoke your own owner permission",
+      deletingHimself: "You can't delete yourself",
+      emailRequired: 'Email is required',
+      slugAlreadyExists: 'This slug is already in use by another project',
+      searchQueryRequired: 'Search query is required',
+    },
+  },
+
+  importer: {
+    errors: {
+      invalidFileEmpty: 'The file is empty',
+      invalidFileExcel: 'Only excel (.xlsx) files are allowed',
+      invalidFileUpload: 'Invalid file. Make sure you are using the last version of the template.',
+      importHashRequired: 'Import hash is required',
+      importHashExistent: 'Data has already been imported',
+      userEmailMissing: 'Some items in the CSV do not have an email',
+    },
+  },
+
+  errors: {
+    forbidden: {
+      message: 'Forbidden',
+    },
+    validation: {
+      message: 'An error occurred',
+    },
+    searchQueryRequired: {
+      message: 'Search query is required',
+    },
+  },
+
+  emails: {
+    invitation: {
+      subject: "You've been invited to {0}",
+      body: '...',
+    },
+    emailAddressVerification: {
+      subject: 'Verify your email for {0}',
+      body: '...',
+    },
+    passwordReset: {
+      subject: 'Reset your password for {0}',
+      body: '...',
+    },
+  },
+};
+
+module.exports = errors;
+```
+
+### Message Categories
+
+| Category | Purpose | Example Key |
+|----------|---------|-------------|
+| `app` | Application metadata | `app.title` |
+| `auth` | Authentication errors | `auth.userNotFound` |
+| `iam` | Identity/access management | `iam.errors.userAlreadyExists` |
+| `importer` | CSV/file import errors | `importer.errors.invalidFileEmpty` |
+| `errors` | Generic error messages | `errors.validation.message` |
+| `emails` | Email subjects/bodies | `emails.invitation.subject` |
+
+---
+
+### Helper Functions (`helpers.js`)
+
+Functions for resolving and formatting notification messages.
+
+```javascript
+const _get = require('lodash/get');
+const errors = require('./list');
+
+/**
+ * Format message with positional arguments
+ * @param {string} message - Message with {0}, {1}, etc. placeholders
+ * @param {Array} args - Arguments to substitute
+ * @returns {string} Formatted message
+ */
+function format(message, args) {
+  if (!message) {
+    return null;
+  }
+
+  return message.replace(/{(\d+)}/g, function (match, number) {
+    return typeof args[number] != 'undefined' ? args[number] : match;
+  });
+}
+
+/**
+ * Check if a key exists in the notification catalog
+ * @param {string} key - Dot-notation path (e.g., 'auth.userNotFound')
+ * @returns {boolean}
+ */
+const isNotification = (key) => {
+  const message = _get(errors, key);
+  return !!message;
+};
+
+/**
+ * Get notification message by key with optional parameter substitution
+ * @param {string} key - Dot-notation path
+ * @param {...any} args - Values to substitute for {0}, {1}, etc.
+ * @returns {string} Resolved message or original key if not found
+ */
+const getNotification = (key, ...args) => {
+  const message = _get(errors, key);
+
+  if (!message) {
+    return key;  // Return raw key as fallback
+  }
+
+  return format(message, args);
+};
+
+exports.getNotification = getNotification;
+exports.isNotification = isNotification;
+```
+
+**Usage Examples:**
+
+```javascript
+const { getNotification, isNotification } = require('./notifications/helpers');
+
+// Simple lookup
+getNotification('auth.userNotFound');
+// → "Sorry, we don't recognize your credentials"
+
+// With parameter substitution
+getNotification('emails.invitation.subject', 'Tour Builder Platform');
+// → "You've been invited to Tour Builder Platform"
+
+// Check if key exists
+isNotification('auth.userNotFound');  // → true
+isNotification('custom.message');      // → false
+
+// Unknown key returns the key itself
+getNotification('unknown.key');
+// → "unknown.key"
+```
+
+---
+
+### Error Classes
+
+#### ValidationError (`errors/validation.js`)
+
+HTTP 400 Bad Request error for validation failures.
+
+```javascript
+const { getNotification, isNotification } = require('../helpers');
+
+module.exports = class ValidationError extends Error {
+  constructor(messageCode) {
+    let message;
+
+    // Try to resolve from notification catalog
+    if (messageCode && isNotification(messageCode)) {
+      message = getNotification(messageCode);
+    }
+
+    // Fallback to generic validation message
+    message = message || getNotification('errors.validation.message');
+
+    super(message);
+    this.code = 400;
+  }
+};
+```
+
+**Properties:**
+- `message` - Human-readable error message
+- `code` - HTTP status code (400)
+
+**Usage:**
+```javascript
+const ValidationError = require('./notifications/errors/validation');
+
+// With catalog key
+throw new ValidationError('auth.userNotFound');
+// → Error: "Sorry, we don't recognize your credentials" (code: 400)
+
+// With unknown key (uses fallback)
+throw new ValidationError('unknown.error');
+// → Error: "An error occurred" (code: 400)
+
+// Without argument
+throw new ValidationError();
+// → Error: "An error occurred" (code: 400)
+```
+
+#### ForbiddenError (`errors/forbidden.js`)
+
+HTTP 403 Forbidden error for authorization failures.
+
+```javascript
+const { getNotification, isNotification } = require('../helpers');
+
+module.exports = class ForbiddenError extends Error {
+  constructor(messageCode) {
+    let message;
+
+    // Try to resolve from notification catalog
+    if (messageCode && isNotification(messageCode)) {
+      message = getNotification(messageCode);
+    }
+
+    // Fallback to generic forbidden message
+    message = message || getNotification('errors.forbidden.message');
+
+    super(message);
+    this.code = 403;
+  }
+};
+```
+
+**Properties:**
+- `message` - Human-readable error message
+- `code` - HTTP status code (403)
+
+**Usage:**
+```javascript
+const ForbiddenError = require('./notifications/errors/forbidden');
+
+// With catalog key
+throw new ForbiddenError('auth.forbidden');
+// → Error: "Forbidden" (code: 403)
+
+// Without argument
+throw new ForbiddenError();
+// → Error: "Forbidden" (code: 403)
+```
+
+---
+
+## Complete Message Reference
+
+### Authentication Messages (`auth.*`)
+
+| Key | Message | Used In |
+|-----|---------|---------|
+| `auth.userDisabled` | "Your account is disabled" | signin |
+| `auth.forbidden` | "Forbidden" | authorization failures |
+| `auth.unauthorized` | "Unauthorized" | missing authentication |
+| `auth.userNotFound` | "Sorry, we don't recognize your credentials" | signin |
+| `auth.wrongPassword` | "Sorry, we don't recognize your credentials" | signin, password update |
+| `auth.weakPassword` | "This password is too weak" | signup, password reset |
+| `auth.emailAlreadyInUse` | "Email is already in use" | signup |
+| `auth.invalidEmail` | "Please provide a valid email" | signup |
+| `auth.userNotVerified` | "Sorry, your email has not been verified yet" | signin |
+| `auth.passwordReset.invalidToken` | "Password reset link is invalid or has expired" | password reset |
+| `auth.passwordReset.error` | "Email not recognized" | password reset request |
+| `auth.passwordUpdate.samePassword` | "You can't use the same password..." | password update |
+| `auth.emailAddressVerificationEmail.invalidToken` | "Email verification link is invalid or has expired" | email verification |
+| `auth.emailAddressVerificationEmail.error` | "Email not recognized" | email verification |
+
+### IAM Messages (`iam.errors.*`)
+
+| Key | Message | Used In |
+|-----|---------|---------|
+| `iam.errors.userAlreadyExists` | "User with this email already exists" | user creation |
+| `iam.errors.userNotFound` | "User not found" | user update/delete |
+| `iam.errors.disablingHimself` | "You can't disable yourself" | user disable |
+| `iam.errors.revokingOwnPermission` | "You can't revoke your own owner permission" | permission revoke |
+| `iam.errors.deletingHimself` | "You can't delete yourself" | user delete |
+| `iam.errors.emailRequired` | "Email is required" | user creation |
+| `iam.errors.slugAlreadyExists` | "This slug is already in use by another project" | project create/update |
+| `iam.errors.searchQueryRequired` | "Search query is required" | search |
+
+### Importer Messages (`importer.errors.*`)
+
+| Key | Message | Used In |
+|-----|---------|---------|
+| `importer.errors.invalidFileEmpty` | "The file is empty" | CSV import |
+| `importer.errors.invalidFileExcel` | "Only excel (.xlsx) files are allowed" | file import |
+| `importer.errors.invalidFileUpload` | "Invalid file..." | file import |
+| `importer.errors.importHashRequired` | "Import hash is required" | bulk import |
+| `importer.errors.importHashExistent` | "Data has already been imported" | duplicate import |
+| `importer.errors.userEmailMissing` | "Some items in the CSV do not have an email" | user CSV import |
+
+### Generic Messages (`errors.*`)
+
+| Key | Message | Used In |
+|-----|---------|---------|
+| `errors.forbidden.message` | "Forbidden" | ForbiddenError default |
+| `errors.validation.message` | "An error occurred" | ValidationError default |
+| `errors.searchQueryRequired.message` | "Search query is required" | search validation |
+
+### Email Messages (`emails.*`)
+
+| Key | Message | Used In |
+|-----|---------|---------|
+| `emails.invitation.subject` | "You've been invited to {0}" | user invitation |
+| `emails.emailAddressVerification.subject` | "Verify your email for {0}" | email verification |
+| `emails.passwordReset.subject` | "Reset your password for {0}" | password reset |
+
+---
+
+## Integration Points
+
+### Services Using Notifications
+
+| Service | Errors Used | Common Keys |
+|---------|-------------|-------------|
+| `auth.js` | ValidationError, ForbiddenError | auth.*, iam.* |
+| `users.ts` | ValidationError | iam.errors.* |
+| `projects.ts` | ValidationError | projectsNotFound |
+| `roles.ts` | ValidationError | rolesNotFound, Public role permission validation |
+| `search.js` | ValidationError | auth.unauthorized, auth.forbidden |
+| `project_audio_tracks.ts` | ValidationError | project_audio_tracksNotFound |
+
+### Email Templates Using Notifications
+
+| Template | Helper Usage |
+|----------|--------------|
+| `passwordReset.js` | `getNotification('emails.passwordReset.subject')` |
+| `addressVerification.js` | `getNotification('emails.emailAddressVerification.subject')` |
+| `invitation.js` | `getNotification('emails.invitation.subject')` |
+
+### Middleware Using Notifications
+
+| Middleware | Error Used | Purpose |
+|------------|------------|---------|
+| `check-permissions.ts` | ValidationError | Permission denied responses |
+
+### Service Factory Using Notifications
+
+```javascript
+// factories/service.factory.js
+const ValidationError = require('../services/notifications/errors/validation');
+
+// Used in update() when entity not found
+if (!record) {
+  throw new ValidationError(`${entityName}NotFound`);
+}
+```
+
+---
+
+## Error Flow
+
+### Error Creation and Propagation
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         Service Layer                               │
+│                                                                     │
+│   const ValidationError = require('./notifications/errors/validation');│
+│                                                                     │
+│   if (!user) {                                                      │
+│     throw new ValidationError('auth.userNotFound');                 │
+│   }                                                                 │
+│                 │                                                   │
+└─────────────────┼───────────────────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                   Notifications Module                              │
+│                                                                     │
+│   1. isNotification('auth.userNotFound') → true                     │
+│   2. getNotification('auth.userNotFound')                           │
+│      → lodash.get(errors, 'auth.userNotFound')                      │
+│      → "Sorry, we don't recognize your credentials"                 │
+│   3. new Error(message) with code = 400                             │
+│                 │                                                   │
+└─────────────────┼───────────────────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     Route Handler                                   │
+│                                                                     │
+│   try {                                                             │
+│     await service.signin(email, password);                          │
+│   } catch (error) {                                                 │
+│     // Error propagates to error handler                            │
+│   }                                                                 │
+│                 │                                                   │
+└─────────────────┼───────────────────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                   Error Handler Middleware                          │
+│                   (index.js)                                        │
+│                                                                     │
+│   app.use((err, req, res, _next) => {                               │
+│     logger.error({ err, url: req.url }, 'Unhandled error');         │
+│     res.status(err.code || 500).json({                              │
+│       message: err.message || 'Internal server error'               │
+│     });                                                             │
+│   });                                                               │
+│                                                                     │
+│   → Response: { "message": "Sorry, we don't recognize your credentials" }│
+│   → Status: 400                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Message Resolution Flow
+
+```
+throw new ValidationError('auth.passwordReset.invalidToken')
+                │
+                ▼
+┌─────────────────────────────────────┐
+│ isNotification(messageCode)        │
+│   lodash.get(errors, key)          │
+│   → "Password reset link..."       │
+│   → true                           │
+└─────────────────┬───────────────────┘
+                  │ (exists)
+                  ▼
+┌─────────────────────────────────────┐
+│ getNotification(messageCode)       │
+│   → "Password reset link is        │
+│      invalid or has expired"       │
+└─────────────────┬───────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│ new Error(message)                 │
+│   this.message = "Password reset..."│
+│   this.code = 400                  │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Comparison: Notifications vs Utils Errors
+
+The backend has two error systems that serve different purposes:
+
+### `services/notifications/errors/` (Primary)
+
+- **Used by**: Services, middleware, service factory
+- **Integration**: Uses notification catalog for i18n
+- **Message resolution**: Dynamic via `getNotification()`
+- **Properties**: `message`, `code`
+
+```javascript
+// notifications/errors/validation.js
+class ValidationError extends Error {
+  constructor(messageCode) {
+    const message = isNotification(messageCode)
+      ? getNotification(messageCode)
+      : getNotification('errors.validation.message');
+    super(message);
+    this.code = 400;
+  }
+}
+```
+
+### `utils/errors.js` (Utility)
+
+- **Used by**: Lower-level utilities
+- **Integration**: Direct message strings
+- **Message resolution**: Static, passed at construction
+- **Properties**: `message`, `statusCode`, `details`, `isOperational`
+
+```javascript
+// utils/errors.js
+class AppError extends Error {
+  constructor(message, statusCode = 500, details = null) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.isOperational = true;
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message, details = null) {
+    super(message, 400, details);
+  }
+}
+```
+
+### When to Use Which
+
+| Scenario | Use |
+|----------|-----|
+| Service business logic errors | `notifications/errors/ValidationError` |
+| Authorization failures | `notifications/errors/ForbiddenError` |
+| Email subject/body text | `getNotification()` |
+| Low-level utility errors | `utils/errors.js` |
+| Errors needing details object | `utils/errors.js` |
+
+---
+
+## Adding New Messages
+
+### 1. Add to Catalog
+
+```typescript
+// services/notifications/list.ts
+const notifications = {
+  // ... existing ...
+
+  projects: {
+    errors: {
+      notFound: 'Project not found',
+      slugTaken: 'A project with this slug already exists',
+      invalidSlug: 'Project slug must contain only letters, numbers, and hyphens',
+    },
+  },
+};
+```
+
+### 2. Use in Service
+
+```javascript
+// services/projects.ts
+const ValidationError = require('./notifications/errors/validation');
+
+async function createProject(data) {
+  const existing = await findBySlug(data.slug);
+  if (existing) {
+    throw new ValidationError('projects.errors.slugTaken');
+  }
+  // ...
+}
+```
+
+### 3. With Parameters
+
+```javascript
+// Add to catalog
+const errors = {
+  projects: {
+    errors: {
+      tooManyPages: 'Project cannot have more than {0} pages',
+    },
+  },
+};
+
+// Use with parameter
+const MAX_PAGES = 100;
+if (pageCount > MAX_PAGES) {
+  const message = getNotification('projects.errors.tooManyPages', MAX_PAGES);
+  throw new ValidationError(message);
+}
+// → "Project cannot have more than 100 pages"
+```
+
+---
+
+## Testing
+
+### Unit Testing Error Classes
+
+```javascript
+describe('ValidationError', () => {
+  it('should resolve message from catalog', () => {
+    const error = new ValidationError('auth.userNotFound');
+    expect(error.message).toBe("Sorry, we don't recognize your credentials");
+    expect(error.code).toBe(400);
+  });
+
+  it('should use fallback for unknown keys', () => {
+    const error = new ValidationError('unknown.key');
+    expect(error.message).toBe('An error occurred');
+    expect(error.code).toBe(400);
+  });
+
+  it('should use fallback without argument', () => {
+    const error = new ValidationError();
+    expect(error.message).toBe('An error occurred');
+  });
+});
+
+describe('ForbiddenError', () => {
+  it('should resolve message from catalog', () => {
+    const error = new ForbiddenError('auth.forbidden');
+    expect(error.message).toBe('Forbidden');
+    expect(error.code).toBe(403);
+  });
+});
+```
+
+### Unit Testing Helpers
+
+```javascript
+const { getNotification, isNotification } = require('./helpers');
+
+describe('getNotification', () => {
+  it('should return message for valid key', () => {
+    expect(getNotification('auth.userNotFound')).toBe(
+      "Sorry, we don't recognize your credentials"
+    );
+  });
+
+  it('should substitute parameters', () => {
+    expect(getNotification('emails.invitation.subject', 'My App')).toBe(
+      "You've been invited to My App"
+    );
+  });
+
+  it('should return key for unknown path', () => {
+    expect(getNotification('unknown.path')).toBe('unknown.path');
+  });
+});
+
+describe('isNotification', () => {
+  it('should return true for existing keys', () => {
+    expect(isNotification('auth.userNotFound')).toBe(true);
+  });
+
+  it('should return false for unknown keys', () => {
+    expect(isNotification('unknown.key')).toBe(false);
+  });
+});
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `lodash/get` | ^4.x | Deep object property access |
+
+---
+
+## Best Practices
+
+### 1. Use Catalog Keys, Not Raw Strings
+
+```javascript
+// Good - uses catalog for consistency
+throw new ValidationError('auth.userNotFound');
+
+// Avoid - raw strings bypass i18n
+throw new ValidationError('User was not found');
+```
+
+### 2. Group Related Messages
+
+```javascript
+// Good - organized by domain
+auth: {
+  passwordReset: {
+    invalidToken: '...',
+    error: '...',
+  }
+}
+
+// Avoid - flat structure
+authPasswordResetInvalidToken: '...',
+authPasswordResetError: '...',
+```
+
+### 3. Security-Conscious Messages
+
+```javascript
+// Good - doesn't reveal if email exists
+userNotFound: "Sorry, we don't recognize your credentials",
+wrongPassword: "Sorry, we don't recognize your credentials",
+
+// Avoid - reveals email existence
+userNotFound: "No account with this email exists",
+wrongPassword: "Password is incorrect",
+```
+
+### 4. Parameter Substitution for Dynamic Content
+
+```javascript
+// Good - parameterized
+subject: "You've been invited to {0}",
+getNotification('emails.invitation.subject', appName);
+
+// Avoid - hardcoded
+subject: "You've been invited to Tour Builder",
+```
+
+---
+
+## Related Documentation
+
+- [Services Module](./services.md) - Service layer error handling
+- [Auth Module](./auth.md) - Authentication errors
+- [Email Module](./email.md) - Email message templates
+- [Middleware Module](./middleware.md) - Permission error handling
diff --git a/backend/docs/modules/routes.md b/backend/docs/modules/routes.md
new file mode 100644
index 0000000..93fe596
--- /dev/null
+++ b/backend/docs/modules/routes.md
@@ -0,0 +1,757 @@
+# Backend Routes Module Documentation
+
+## Overview
+
+The Routes module defines all HTTP endpoints for the application. It uses a factory pattern for entity CRUD operations and custom routes for specialized functionality.
+
+**Directory:** `src/routes/`
+
+**Files (25 total):**
+| File | Lines | Pattern | Description |
+|------|-------|---------|-------------|
+| `auth.ts` | 327 | Custom | Authentication endpoints |
+| `file.ts` | 150 | Custom | File upload/download endpoints |
+| `publish.ts` | 107 | Custom | Publishing workflow endpoints |
+| `search.ts` | 64 | Custom | Global search endpoint |
+| `runtime-context.ts` | 16 | Custom | Runtime context inspection |
+| `projects.ts` | 46 | Hybrid | Projects CRUD + custom clone endpoint |
+| `users.ts` | 64 | Hybrid | Users CRUD via factory + sanitized GET by ID |
+| `tour_pages.ts` | 380 | Manual CRUD | Tour pages CRUD plus reorder, duplicate, reverse-video status |
+| `roles.ts` | 141 | Factory | Roles CRUD via factory |
+| `permissions.ts` | 188 | Factory | Permissions CRUD via factory |
+| `assets.ts` | 155 | Factory | Assets CRUD via factory |
+| `asset_variants.ts` | 147 | Factory | Asset variants CRUD via factory |
+| `access_logs.ts` | 145 | Factory | Access logs CRUD via factory |
+| `project_memberships.ts` | 145 | Factory | Project memberships CRUD via factory |
+| `project_audio_tracks.ts` | 151 | Factory | Project audio tracks CRUD via factory |
+| `global_transition_defaults.ts` | 145 | Custom | Runtime-readable global transition defaults |
+| `global_ui_control_defaults.ts` | 79 | Custom | Runtime-readable global UI-control defaults |
+| `project_transition_settings.ts` | 212 | Custom | Project/environment transition overrides |
+| `project_ui_control_settings.ts` | 125 | Custom | Project/environment global UI-control overrides |
+| `presigned_url_requests.ts` | 150 | Factory | Presigned URL requests CRUD via factory |
+| `publish_events.ts` | 157 | Factory | Publish events CRUD via factory |
+| `pwa_caches.ts` | 148 | Factory | PWA caches CRUD via factory |
+| `element_type_defaults.ts` | 12 | Factory | Element type defaults via factory |
+| `project_element_defaults.ts` | 92 | Hybrid | Project element defaults CRUD + custom (reset, diff) |
+
+---
+
+## Architecture Diagram
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                         Route Patterns                               │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  ┌─────────────────────────────────────────────────────────────────┐ │
+│  │ Factory Pattern (createEntityRouter)                            │ │
+│  │                                                                 │ │
+│  │  routes/roles.ts ──────────────┐                                │ │
+│  │  routes/permissions.ts ────────┤                                │ │
+│  │  routes/assets.ts ─────────────┼───▶ factories/router.factory.ts│ │
+│  │  routes/asset_variants.ts ─────┤                                │ │
+│  │  routes/access_logs.ts ────────┤     Generates:                 │ │
+│  │  routes/pwa_caches.ts ─────────┤     • POST /                   │ │
+│  │  routes/publish_events.ts ─────┤     • POST /bulk-import        │ │
+│  │  routes/element_type_defaults.ts     • PUT /:id                 │ │
+│  │  routes/presigned_url_requests.ts    • DELETE /:id              │ │
+│  │  routes/project_memberships.ts       • POST /deleteByIds        │ │
+│  │  routes/project_audio_tracks.ts      • GET /                    │ │
+│  │  ... (11 entities)                   • GET /count               │ │
+│  │                                      • GET /autocomplete        │ │
+│  │                                      • GET /:id                 │ │
+│  └─────────────────────────────────────────────────────────────────┘ │
+│                                                                      │
+│  ┌─────────────────────────────────────────────────────────────────┐ │
+│  │ Hybrid Pattern (Factory + Custom Routes)                        │ │
+│  │                                                                 │ │
+│  │  routes/projects.ts ──────────────────┐                         │ │
+│  │     • Standard CRUD (manual)          │                         │ │
+│  │     + POST /:id/clone                 │                         │ │
+│  │     + GET /:id/offline-manifest       │                         │ │
+│  │                                       │                         │ │
+│  │  routes/project_element_defaults.ts ──┘                         │ │
+│  │     • Standard CRUD (factory)                                   │ │
+│  │     + POST /:id/reset                                           │ │
+│  │     + GET /:id/diff                                             │ │
+│  └─────────────────────────────────────────────────────────────────┘ │
+│                                                                      │
+│  ┌─────────────────────────────────────────────────────────────────┐ │
+│  │ Custom Pattern (Full Manual Implementation)                     │ │
+│  │                                                                 │ │
+│  │  routes/auth.ts ───────── Authentication flows                  │ │
+│  │  routes/file.ts ───────── File upload/download                  │ │
+│  │  routes/publish.ts ────── Publishing workflow                   │ │
+│  │  routes/search.ts ─────── Global search                         │ │
+│  │  routes/runtime-context.ts ─ Runtime inspection                 │ │
+│  └─────────────────────────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Route Factory
+
+### factories/router.factory.ts
+
+Generates standardized CRUD routes for entities.
+
+```javascript
+const router = createEntityRouter(
+  'tour_pages',        // Entity name
+  Tour_pagesService,   // Service class
+  Tour_pagesDBApi,     // Database API class
+  {
+    permissionEntity: 'tour_pages',  // Permission entity name (optional)
+    csvFields: ['id', 'name'],       // CSV export fields (optional)
+    validation: {                    // Request validation overrides (optional)
+      create: customCreateSchema,
+      update: customUpdateSchema,
+    },
+    customRoutes: (router, Service, DBApi) => {  // Custom routes (optional)
+      router.post('/custom', handler);
+    }
+  }
+);
+```
+
+#### Generated Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/` | Create new item |
+| `POST` | `/bulk-import` | Bulk import items |
+| `PUT` | `/:id` | Update item by ID |
+| `DELETE` | `/:id` | Delete item by ID |
+| `POST` | `/deleteByIds` | Delete multiple items |
+| `GET` | `/` | List items (with pagination, filters) |
+| `GET` | `/count` | Count items matching filters |
+| `GET` | `/autocomplete` | Autocomplete search |
+| `GET` | `/:id` | Get single item by ID |
+
+#### Factory Features
+
+**Permission Checking:**
+```javascript
+router.use(checkCrudPermissions(permissionEntity));
+// Maps HTTP methods to permissions:
+// GET → READ_ENTITY
+// POST → CREATE_ENTITY
+// PUT/PATCH → UPDATE_ENTITY
+// DELETE → DELETE_ENTITY
+```
+
+**Request Validation:**
+```typescript
+import { validateRequest } from '../middlewares/validate-request.ts';
+import { crud as crudSchemas } from '../validators/request-schemas.ts';
+
+router.get(
+  '/:id',
+  validateRequest(crudSchemas.findOne),
+  wrapAsync(async (req, res) => {
+    const payload = await DBApi.findBy({ id: req.params.id });
+    res.status(200).send(payload);
+  }),
+);
+```
+
+Factory CRUD routes validate request bodies, params, and common query controls before service/DB calls. List and count routes validate `limit`, `page`, `field`, `sort`, and `filetype` while keeping existing entity filter query parameters. Entity routers can pass `validation` overrides for stricter contracts, as `users` and `projects` do.
+
+**CSV Export:**
+```javascript
+// GET /?filetype=csv
+if (filetype === 'csv') {
+  const csv = parse(payload.rows, { fields });
+  res.status(200).attachment('export.csv').send(csv);
+}
+```
+
+**Runtime Context:**
+```javascript
+const runtimeContext = req.runtimeContext;
+const payload = await DBApi.findAll(req.query, {
+  currentUser,
+  runtimeContext,
+});
+```
+
+---
+
+## Route Mounting (index.js)
+
+Routes are mounted with authentication and rate limiting:
+
+```javascript
+// No auth required
+app.use('/api/auth', authRoutes);
+app.use('/api/runtime-context', runtimeContextRoutes);
+app.get('/api/health', healthHandler);
+
+// File routes (before body parser)
+app.use('/api/file/download', downloadLimiter);
+app.use('/api/file/presign', downloadLimiter);
+app.use('/api/file/upload', uploadLimiter);
+app.use('/api/file', fileRoutes);
+
+// JWT auth required
+app.use('/api/users', jwtAuth, usersRoutes);
+app.use('/api/roles', jwtAuth, rolesRoutes);
+app.use('/api/permissions', jwtAuth, permissionsRoutes);
+app.use('/api/project_memberships', jwtAuth, project_membershipsRoutes);
+app.use('/api/assets', jwtAuth, assetsRoutes);
+app.use('/api/asset_variants', jwtAuth, asset_variantsRoutes);
+app.use('/api/presigned_url_requests', jwtAuth, presigned_url_requestsRoutes);
+app.use('/api/publish_events', jwtAuth, publish_eventsRoutes);
+app.use('/api/pwa_caches', jwtAuth, pwa_cachesRoutes);
+app.use('/api/access_logs', jwtAuth, access_logsRoutes);
+app.use('/api/element-type-defaults', jwtAuth, element_type_defaultsRoutes);
+app.use('/api/project-element-defaults', jwtAuth, project_element_defaultsRoutes);
+app.use('/api/publish', jwtAuth, publishRoutes);
+
+// JWT + Rate limiting
+app.use('/api/search', jwtAuth, searchLimiter, searchRoutes);
+
+// Runtime public access (production environment)
+mountRuntimeEntityRoute('/api/projects', 'projects', projectsRoutes);
+mountRuntimeEntityRoute('/api/tour_pages', 'tour_pages', tour_pagesRoutes);
+mountRuntimeEntityRoute('/api/project_audio_tracks', 'project_audio_tracks', ...);
+```
+
+---
+
+## Custom Routes Detail
+
+### 1. auth.ts (327 lines)
+
+Authentication and account management.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/signin/local` | No | Email/password login |
+| POST | `/signup` | No | Register new user |
+| GET | `/me` | JWT | Get current user |
+| PUT | `/password-reset` | No | Reset password with token |
+| PUT | `/password-update` | JWT | Change password |
+| PUT | `/profile` | JWT | Update user profile |
+| PUT | `/verify-email` | No | Verify email with token |
+| POST | `/send-email-address-verification-email` | JWT | Resend verification |
+| POST | `/send-password-reset-email` | No | Send reset email |
+| GET | `/email-configured` | No | Check email config |
+| GET | `/signin/google` | No | Google OAuth start |
+| GET | `/signin/google/callback` | No | Google OAuth callback |
+| GET | `/signin/microsoft` | No | Microsoft OAuth start |
+| GET | `/signin/microsoft/callback` | No | Microsoft OAuth callback |
+
+`auth.ts` is a typed ESM route boundary. It uses reusable request body/query contracts from `backend/src/types/auth-routes.ts`, the typed `backend/src/services/auth.ts` service, and the shared Passport helpers in `backend/src/auth/passport-middleware.ts`.
+
+---
+
+### 2. file.ts (150 lines)
+
+File upload and download operations.
+
+`file.ts` is a typed ESM route boundary. It calls the typed unified storage facade in `backend/src/services/file.ts`, while provider contracts and request/response shapes live in reusable `backend/src/types/file.ts` contracts. S3 and GCloud use official SDK-provided types instead of local SDK declarations.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/download` | No | Download file by privateUrl |
+| POST | `/presign` | No | Generate presigned URLs (max 50) |
+| POST | `/upload/:table/:field` | JWT | Legacy single file upload |
+| POST | `/upload-sessions/init` | JWT | Initialize chunked upload |
+| GET | `/upload-sessions/:sessionId` | JWT | Get upload session status |
+| PUT | `/upload-sessions/:sessionId/chunks/:chunkIndex` | JWT | Upload chunk |
+| POST | `/upload-sessions/:sessionId/finalize` | JWT | Finalize chunked upload |
+
+**Presigned URLs Request:**
+```json
+{
+  "urls": ["assets/image.jpg", "assets/video.mp4"]
+}
+```
+
+**Presigned URLs Response:**
+```json
+{
+  "presignedUrls": {
+    "assets/image.jpg": "https://s3.../assets/image.jpg?X-Amz-...",
+    "assets/video.mp4": "https://s3.../assets/video.mp4?X-Amz-..."
+  }
+}
+```
+
+---
+
+### 3. publish.ts (107 lines)
+
+Publishing workflow for Dev → Stage → Production.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/` | JWT | Publish stage to production |
+| POST | `/publish` | JWT | Alias for publish |
+| POST | `/save-to-stage` | JWT | Save dev to stage |
+
+**Publish Request:**
+```json
+{
+  "projectId": "uuid",
+  "title": "Release 1.0",
+  "description": "Initial release"
+}
+```
+
+**Save to Stage Request:**
+```json
+{
+  "projectId": "uuid"
+}
+```
+
+---
+
+### 4. search.ts (64 lines)
+
+Global full-text search across entities.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/` | JWT | Search across all entities |
+
+**Request:**
+```json
+{
+  "searchQuery": "my search term"
+}
+```
+
+**Response:**
+```json
+{
+  "users": [...],
+  "projects": [...],
+  "tour_pages": [...]
+}
+```
+
+### 5. runtime-context.ts (16 lines)
+
+Runtime context inspection for debugging.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/` | No | Get current runtime context |
+
+**Response:**
+```json
+{
+  "mode": "admin",
+  "projectSlug": null,
+  "headerEnvironment": "production",
+  "headerProjectSlug": "my-tour"
+}
+```
+
+---
+
+## Entity Routes Detail
+
+### projects.ts (46 lines)
+
+Projects with factory CRUD plus a clone endpoint.
+
+**Standard CRUD Endpoints:**
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/` | Create project |
+| POST | `/bulk-import` | Bulk import projects |
+| PUT | `/:id` | Update project |
+| DELETE | `/:id` | Delete project |
+| POST | `/deleteByIds` | Delete multiple projects |
+| GET | `/` | List projects |
+| GET | `/count` | Count projects |
+| GET | `/autocomplete` | Autocomplete search |
+| GET | `/:id` | Get project by ID |
+
+**Custom Endpoints:**
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/:id/clone` | Clone project with all pages |
+---
+
+### tour_pages.ts (380 lines)
+
+Typed manual CRUD route for tour pages. In addition to standard create/update/delete/list/count/autocomplete/find-by-id operations, it owns page reorder, dev-page duplication, CSV export, and reverse-video status endpoints. The route uses reusable contracts from `backend/src/types/tour-pages.ts`.
+
+**Schema Fields:**
+- `source_key`, `name`, `slug`
+- `background_image_url`, `background_video_url`, `background_audio_url`
+- `ui_schema_json`, `sort_order`
+
+**Endpoints:**
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/` | Create page |
+| POST | `/bulk-import` | Bulk import pages |
+| POST | `/reorder` | Reorder dev pages in a project/environment |
+| POST | `/:id/duplicate` | Duplicate a dev page |
+| PUT | `/:id` | Update page |
+| DELETE | `/:id` | Remove page |
+| POST | `/deleteByIds` | Remove multiple pages |
+| GET | `/` | List pages with reverse video URL population and optional CSV export |
+| POST | `/reverse-video-status` | Check generated reverse-video variants |
+| GET | `/count` | Count pages |
+| GET | `/autocomplete` | Page autocomplete |
+| GET | `/:id` | Get one page with reverse video URL population |
+- `POST /api/tour_pages/reorder` accepts `{ data: { projectId, environment,
+  orderedPageIds } }`, validates a complete page list for the project/dev
+  environment, and updates only `sort_order`.
+- `POST /api/tour_pages/:id/duplicate` accepts `{ data: { projectId,
+  environment, name, slug } }`, duplicates a dev page into a new independent dev
+  page, appends it to the project order, deep-copies `ui_schema_json`, and
+  regenerates inline element IDs.
+- Constructor page deletion uses the standard `DELETE /api/tour_pages/:id`
+  route after a frontend confirmation modal; no separate delete endpoint is
+  needed.
+- Custom routes are protected by Passport JWT like other tour page mutations and
+  are implemented before `/:id` where needed so custom paths are not treated as
+  entity IDs.
+- Non-dev environments are rejected for reorder and duplicate; stage and
+  production changes only flow through Save to Stage and Publish.
+
+---
+
+### element_type_defaults.ts (12 lines)
+
+Minimal factory usage with permission override.
+
+```javascript
+module.exports = createEntityRouter(
+  'element_type_defaults',
+  Element_type_defaultsService,
+  Element_type_defaultsDBApi,
+  {
+    permissionEntity: 'page_elements',  // Uses PAGE_ELEMENTS permissions
+  },
+);
+```
+
+**URL Aliases:**
+- `/api/element-type-defaults` (primary)
+- `/api/ui-elements` (backwards compatibility)
+
+---
+
+### project_element_defaults.ts (92 lines)
+
+Factory-generated routes plus custom endpoints for resetting and comparing defaults.
+
+```javascript
+const baseRouter = createEntityRouter(
+  'project_element_defaults',
+  Project_element_defaultsService,
+  Project_element_defaultsDBApi,
+  {
+    permissionEntity: 'page_elements',
+  },
+);
+
+// Add custom endpoints
+baseRouter.post('/:id/reset', ...);
+baseRouter.get('/:id/diff', ...);
+```
+
+**Standard CRUD Endpoints:** (via factory)
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/` | Create project element default |
+| PUT | `/:id` | Update project element default |
+| DELETE | `/:id` | Delete project element default |
+| GET | `/` | List project element defaults |
+| GET | `/:id` | Get project element default by ID |
+
+**Custom Endpoints:**
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/:id/reset` | Reset project element default to global |
+| GET | `/:id/diff` | Get diff from global element type default |
+
+**URL Alias:**
+- `/api/project-element-defaults` (primary)
+
+---
+
+## Request/Response Patterns
+
+### List Endpoint (GET /)
+
+**Query Parameters:**
+| Param | Type | Description |
+|-------|------|-------------|
+| `page` | number | Page number (0-indexed) |
+| `limit` | number | Items per page |
+| `field` | string | Sort field |
+| `sort` | string | Sort direction (`asc`/`desc`) |
+| `filetype` | string | Export format (`csv`) |
+| `[fieldName]` | string | Filter by field value |
+| `[fieldName]Range` | array | Filter by range `[start, end]` |
+
+**Response:**
+```json
+{
+  "rows": [...],
+  "count": 150
+}
+```
+
+### Create Endpoint (POST /)
+
+**Request:**
+```json
+{
+  "data": {
+    "name": "New Item",
+    "field1": "value1"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "id": "uuid",
+  "name": "New Item",
+  "field1": "value1",
+  "createdAt": "2024-01-01T00:00:00.000Z"
+}
+```
+
+### Update Endpoint (PUT /:id)
+
+**Request:**
+```json
+{
+  "id": "uuid",
+  "data": {
+    "name": "Updated Name"
+  }
+}
+```
+
+**Response:**
+```json
+true
+```
+
+### Delete Endpoints
+
+**Single Delete (DELETE /:id):**
+```json
+true
+```
+
+**Bulk Delete (POST /deleteByIds):**
+```json
+{
+  "data": ["uuid1", "uuid2", "uuid3"]
+}
+```
+
+---
+
+## Swagger Documentation
+
+Swagger UI is served at `GET /api-docs`. The OpenAPI document is maintained in
+`backend/src/openapi/document.ts`, not in route-local JSDoc comments.
+
+```javascript
+const specs = createOpenApiDocument({
+  serverUrl: config.server.swaggerServerUrl,
+});
+```
+
+The OpenAPI module contains:
+
+- Shared schemas for auth, users, projects, tour pages, assets, publishing,
+  runtime access, file upload, UI controls, transition settings, and audit
+  entities.
+- A reusable factory CRUD path generator covering `POST /`, `POST /bulk-import`,
+  `PUT /:id`, `DELETE /:id`, `POST /deleteByIds`, `GET /`, `GET /count`,
+  `GET /autocomplete`, and `GET /:id`.
+- Explicit path definitions for custom routes such as auth flows, publishing,
+  file upload/download, runtime access/context, project clone, tour page reorder
+  and duplicate, transition/UI-control settings, and project element default
+  reset/diff.
+
+When adding routes, update `backend/src/openapi/document.ts` alongside the route
+implementation. For factory-backed entities, add a schema and `CrudResource`
+entry instead of copying per-route Swagger boilerplate.
+
+**Access Swagger UI:** `http://localhost:3000/api-docs` in local development.
+
+On the standard VM, the backend runs in `NODE_ENV=dev_stage` on port `3000`;
+Apache serves the public domain on port `80`. See
+[`deployment-vm.md`](../../../documentation/deployment-vm.md) for VM health checks.
+
+---
+
+## Error Handling
+
+### wrapAsync Helper
+
+All async route handlers use `wrapAsync` for error propagation:
+
+```javascript
+router.post(
+  '/',
+  wrapAsync(async (req, res) => {
+    // Errors thrown here are caught and passed to error handler
+    const payload = await Service.create({
+      data: req.body.data,
+      currentUser: req.currentUser,
+      runtimeContext: req.runtimeContext,
+    });
+    res.status(200).send(payload);
+  }),
+);
+```
+
+### commonErrorHandler
+
+Each route file includes error handler:
+
+```javascript
+router.use('/', require('../helpers').commonErrorHandler);
+```
+
+**Error Response Mapping:**
+| Status Code | Description |
+|-------------|-------------|
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 409 | Conflict |
+| 422 | Unprocessable Entity |
+| 500 | Internal Server Error |
+
+---
+
+## Route Categories
+
+### Public Routes (No Auth)
+
+| Route | Description |
+|-------|-------------|
+| `GET /api/health` | Health check |
+| `POST /api/auth/signin/local` | Login |
+| `GET /api/auth/signin/google` | Google OAuth |
+| `GET /api/auth/signin/microsoft` | Microsoft OAuth |
+| `GET /api/file/download` | File download |
+| `POST /api/file/presign` | Generate presigned URLs |
+| `GET /api/runtime-context` | Runtime context |
+
+### Runtime Public Routes (Production Environment)
+
+| Route | Description |
+|-------|-------------|
+| `GET /api/projects` | List projects (sanitized) |
+| `GET /api/tour_pages` | List tour pages (sanitized) |
+| `GET /api/project_audio_tracks` | List audio tracks (sanitized) |
+
+### Authenticated Routes (JWT Required)
+
+All other routes require JWT authentication via:
+```javascript
+app.use('/api/users', jwtAuth, usersRoutes);
+```
+
+### Rate Limited Routes
+
+| Route | Limiter | Config |
+|-------|---------|--------|
+| `/api/auth/signin/local` | authLimiter | 10/15min |
+| `/api/auth/send-password-reset-email` | passwordResetLimiter | 5/hour |
+| `/api/file/upload*` | uploadLimiter | 10/min |
+| `/api/file/download`, `/presign` | downloadLimiter | 200/min |
+| `/api/search` | searchLimiter | 30/min |
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `express` | Router and middleware |
+| `json2csv` | CSV export functionality |
+| `passport` | JWT authentication |
+| `body-parser` | JSON body parsing |
+
+---
+
+## Testing
+
+### Test Entity CRUD
+
+```bash
+# Create
+curl -X POST http://localhost:3000/api/projects \
+  -H "Authorization: Bearer <JWT>" \
+  -H "Content-Type: application/json" \
+  -d '{"data": {"name": "Test Project", "slug": "test"}}'
+
+# List
+curl http://localhost:3000/api/projects \
+  -H "Authorization: Bearer <JWT>"
+
+# Get by ID
+curl http://localhost:3000/api/projects/<uuid> \
+  -H "Authorization: Bearer <JWT>"
+
+# Update
+curl -X PUT http://localhost:3000/api/projects/<uuid> \
+  -H "Authorization: Bearer <JWT>" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "<uuid>", "data": {"name": "Updated Name"}}'
+
+# Delete
+curl -X DELETE http://localhost:3000/api/projects/<uuid> \
+  -H "Authorization: Bearer <JWT>"
+```
+
+### Test Public Runtime
+
+```bash
+curl http://localhost:3000/api/projects \
+  -H "X-Runtime-Environment: production"
+```
+
+### Test Presigned URLs
+
+```bash
+curl -X POST http://localhost:3000/api/file/presign \
+  -H "Content-Type: application/json" \
+  -d '{"urls": ["assets/test.jpg"]}'
+```
+
+---
+
+## Summary
+
+The Routes module provides:
+
+1. **Factory Pattern** - 12 entities with standardized CRUD (createEntityRouter)
+2. **Hybrid Pattern** - 2 entities with factory CRUD + custom endpoints (projects, project_element_defaults)
+3. **Custom Routes** - 7 specialized route files for auth, files, search, etc.
+4. **Swagger Documentation** - centralized OpenAPI document for all endpoints
+5. **Permission Checking** - RBAC via checkCrudPermissions middleware
+6. **Runtime Public Access** - Production environment public read access
+7. **Rate Limiting** - Per-endpoint rate limiting
+8. **CSV Export** - Export capability via `?filetype=csv`
+9. **Request Validation** - Joi schemas via validateRequest before service calls
+10. **Error Handling** - Centralized via wrapAsync and commonErrorHandler
+
+**Route Statistics:**
+- 26 route files
+- ~50+ unique endpoints
+- 11 factory-generated entity routers
+- 3 hybrid entity routers (factory + custom)
+- 7 custom route implementations
diff --git a/backend/docs/modules/services.md b/backend/docs/modules/services.md
new file mode 100644
index 0000000..e6115e8
--- /dev/null
+++ b/backend/docs/modules/services.md
@@ -0,0 +1,1142 @@
+# Backend Services Module
+
+## Overview
+
+The Services module implements the **business logic layer** of the backend application. Services sit between routes (controllers) and the database API layer, encapsulating complex operations, transaction management, and cross-cutting concerns.
+
+**Location:** `backend/src/services/`
+
+**Total Files:** 37 (24 root services + 13 subdirectory files)
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                           Routes Layer                              │
+│                    (HTTP Request Handling)                          │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                         Services Layer                              │
+│  ┌───────────────────────────────────────────────────────────────┐  │
+│  │                    Service Categories                         │  │
+│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │  │
+│  │  │   Factory   │ │   Custom    │ │ Specialized │              │  │
+│  │  │  Services   │ │  Services   │ │  Modules    │              │  │
+│  │  │ (9 files)   │ │ (12 files)  │ │ (3 dirs)    │              │  │
+│  │  └─────────────┘ └─────────────┘ └─────────────┘              │  │
+│  └───────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                       Database API Layer                            │
+│                 (Sequelize ORM Operations)                          │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Service Categories
+
+### 1. Factory-Generated Services (Simple CRUD)
+
+Generated using `createEntityService()` from `factories/service.factory.ts`. These provide standardized CRUD operations with transaction handling.
+
+| Service | File | Entity | LOC |
+|---------|------|--------|-----|
+| tour_pages | `tour_pages.ts` | Tour Pages (includes reverse video generation) | ~1,300 |
+| permissions | `permissions.ts` | Permissions | 6 |
+| asset_variants | `asset_variants.ts` | Asset Variants | 6 |
+| presigned_url_requests | `presigned_url_requests.ts` | Presigned URL Requests | 6 |
+| publish_events | `publish_events.ts` | Publish Events | 6 |
+| pwa_caches | `pwa_caches.ts` | PWA Caches | 6 |
+| access_logs | `access_logs.ts` | Access Logs | 6 |
+| element_type_defaults | `element_type_defaults.ts` | Element Type Defaults | 6 |
+| project_memberships | `project_memberships.ts` | Project Memberships | 6 |
+| global_transition_defaults | `global_transition_defaults.ts` | Global transition defaults | 6 |
+
+**Example - Factory Service:**
+```javascript
+// permissions.ts
+import PermissionsDBApi from '../db/api/permissions.ts';
+import { createEntityService } from '../factories/service.factory.ts';
+
+export default createEntityService(PermissionsDBApi, {
+  entityName: 'permissions',
+});
+```
+
+### 2. Custom Services (Business Logic)
+
+Services with domain-specific business logic beyond simple CRUD.
+
+| Service | File | Purpose | LOC |
+|---------|------|---------|-----|
+| assets | `assets.ts` | Asset management, MIME validation, embed URL validation, stored media metadata probing | ~300 |
+| auth | `auth.ts` | Authentication, password reset, email verification | ~210 |
+| users | `users.ts` | User management, invitation emails, Public viewer grants | ~350 |
+| projects | `projects.ts` | Project cloning, slug generation, slug uniqueness validation | ~680 |
+| roles | `roles.ts` | Role management, permission assignment, CSV import, Public-role hardening | ~170 |
+| file | `file.ts` | Multi-provider file storage, downloadToBuffer, uploadBuffer, S3/GCloud circuit breaker for processing paths | ~1,600 |
+| publish | `publish.ts` | Dev→Stage→Production publishing | ~400 |
+| search | `search.ts` | Global full-text search | 178 |
+| pwa_manifest | `pwa_manifest.js` | PWA offline manifest generation | 315 |
+| project_audio_tracks | `project_audio_tracks.ts` | Audio track management | 117 |
+| project_transition_settings | `project_transition_settings.ts` | Environment-aware transition settings | 209 |
+| project_element_defaults | `project_element_defaults.ts` | Element defaults with reset/diff | 34 |
+| global_ui_control_defaults | `global_ui_control_defaults.ts` | Global defaults CRUD service for system controls | 6 |
+| project_ui_control_settings | `project_ui_control_settings.ts` | Transactional find/upsert/delete for project UI-control overrides | 51 |
+| videoProcessing | `videoProcessing.ts` | FFmpeg video reversal for transition videos with single-worker queue, `-threads 1`, hard timeout, metadata logs, and circuit breaker | ~240 |
+
+### 3. Specialized Module Directories
+
+```
+services/
+├── file/                    # Storage providers (Strategy Pattern)
+│   ├── BaseStorageProvider.ts     # Abstract interface
+│   ├── S3StorageProvider.ts       # AWS S3 implementation
+│   ├── LocalStorageProvider.ts    # Local filesystem
+│   ├── UploadSessionManager.ts    # Chunked uploads
+│   └── index.js                   # Provider factory (27 LOC)
+│
+├── email/                   # Email sending
+│   ├── index.js                   # EmailSender class (44 LOC)
+│   └── list/
+│       ├── passwordReset.ts       # Password reset email
+│       ├── addressVerification.ts # Email verification
+│       └── invitation.ts          # User invitation email
+│
+└── notifications/           # Error handling & i18n
+    ├── helpers.js                 # getNotification helper (30 LOC)
+    ├── list.js                    # Error message catalog (100 LOC)
+    └── errors/
+        ├── validation.js          # ValidationError class (16 LOC)
+        └── forbidden.js           # ForbiddenError class (16 LOC)
+```
+
+---
+
+## Service Factory Pattern
+
+### `factories/service.factory.ts`
+
+Generates standardized service classes with transaction handling.
+
+```javascript
+function createEntityService(DBApi, options = {}) {
+  const entityName = options.entityName || 'Entity';
+
+  return class GenericService {
+    // Create with transaction
+    static async create({ data, currentUser, transaction, runtimeContext }) {
+      const transaction = await db.sequelize.transaction();
+      try {
+        const record = await DBApi.create({ data, currentUser, transaction, runtimeContext });
+        await transaction.commit();
+        return record;
+      } catch (error) {
+        await transaction.rollback();
+        throw error;
+      }
+    }
+
+    // Bulk import from CSV
+    static async bulkImport(req, res) { ... }
+
+    // Update with existence check
+    static async update({ id, data, currentUser, transaction, runtimeContext }) { ... }
+
+    // Delete multiple by IDs
+    static async deleteByIds({ ids, currentUser, transaction, runtimeContext }) { ... }
+
+    // Soft delete single
+    static async remove({ id, currentUser, transaction, runtimeContext }) { ... }
+  };
+}
+```
+
+**Generated Methods:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `create` | `(data, currentUser) → record` | Create with transaction |
+| `bulkImport` | `(req, res) → void` | CSV import with validation |
+| `update` | `(data, id, currentUser) → record` | Update with existence check |
+| `deleteByIds` | `(ids, currentUser) → void` | Bulk soft delete |
+| `remove` | `(id, currentUser) → void` | Single soft delete |
+
+---
+
+## Core Services Detail
+
+### Tour Pages Service (`tour_pages.ts`)
+
+Extends the factory-generated CRUD service with page-specific operations.
+
+**Reorder operation:**
+- `TourPagesService.reorder(data, currentUser)` accepts `projectId`,
+  `environment`, and `orderedPageIds`.
+- Reordering is allowed only for `environment='dev'`; this preserves the
+  publishing model where stage and production are derived environments.
+- The service loads all pages for the project/dev environment inside a
+  transaction, verifies that the ordered list contains every page exactly once,
+  and then updates `sort_order` sequentially.
+- The operation updates only `sort_order`; it does not change page content,
+  slugs, backgrounds, `ui_schema_json`, navigation, transitions, or media.
+- Stage receives the new order after Save to Stage; production receives it after
+  Publish.
+
+### Auth Service (`auth.ts`)
+
+Handles authentication, password management, and email verification.
+
+```typescript
+class Auth {
+  // User login with bcrypt verification
+  static async signin(email, password) → JWT
+
+  // Send email verification link
+  static async sendEmailAddressVerificationEmail(email, host)
+
+  // Send password reset or invitation email
+  static async sendPasswordResetEmail(email, type, host)
+
+  // Verify email from token
+  static async verifyEmail(token, options) → boolean
+
+  // Update password (requires current password)
+  static async passwordUpdate(currentPassword, newPassword, options)
+
+  // Reset password from token
+  static async passwordReset(token, password, options)
+
+  // Update user profile
+  static async updateProfile(data, currentUser)
+}
+```
+
+**Security Features:**
+- bcrypt password hashing (`config.bcrypt.saltRounds`)
+- JWT token generation via `helpers.jwtSign()`
+- Email verification required for login
+- Password reset tokens with expiration
+
+### Assets Service (`assets.ts`)
+
+Extended factory service with strict reusable TypeScript contracts, MIME type validation for asset uploads, embed URL validation, and stored audio/video metadata probing.
+
+```typescript
+class AssetsService extends BaseService {
+  // Create asset with MIME type validation
+  static async create({ data, currentUser, transaction, runtimeContext })
+
+  // Update asset with MIME type validation
+  static async update({ id, data, currentUser, transaction, runtimeContext })
+}
+```
+
+**MIME Type Validation:**
+
+| Asset Type | Valid MIME Prefixes | Description |
+|------------|---------------------|-------------|
+| `image` | `image/` | JPEG, PNG, GIF, WebP, SVG, etc. |
+| `video` | `video/` | MP4, WebM, MOV, etc. |
+| `audio` | `audio/` | MP3, WAV, OGG, etc. |
+| `embed` | n/a | MIME validation skipped; HTTPS embed URL domain is validated |
+
+**Validation Rules:**
+- `asset_type` and `mime_type` must be consistent
+- If `asset_type` is `image`, `mime_type` must start with `image/`
+- If `asset_type` is `video`, `mime_type` must start with `video/`
+- If `asset_type` is `audio`, `mime_type` must start with `audio/`
+- Asset types not in the validation list (e.g., `file`) skip validation
+- Missing `mime_type` is allowed (browser may not always send it)
+
+**Error Response:**
+```javascript
+throw new ValidationError(
+  `Invalid file type for ${assetType}. Expected ${patterns.description}, got "${mimeType}"`
+);
+```
+
+---
+
+### File Service (`file.js`)
+
+Unified file storage using Strategy Pattern for multiple backends. Features comprehensive error handling,
+AbortController support for client disconnect handling, path validation for security, and structured Pino logging.
+
+```javascript
+// Provider auto-detection
+const getFileStorageProvider = () → 's3' | 'gcloud' | 'local'
+
+// Core operations (with AbortController support for S3)
+const uploadFile = async (folder, req, res) → { url }
+const downloadFile = async (req, res) → stream  // Aborts on client disconnect
+const deleteFile = async (privateUrl, { throwOnError }) → { success, error? }
+
+// Server-side file copy (S3 uses CopyObjectCommand, Local uses fs.copyFile)
+const copyFile = async (sourceKey, destKey, options) → { url } | { key }
+const copyFilesParallel = async (copies, options) → { succeeded, failed }
+
+// Chunked upload session management
+const initUploadSession = async (req, res) → { sessionId, totalChunks }
+const getUploadSession = async (req, res) → { status, uploadedChunks }
+const uploadChunk = async (req, res) → { chunkIndex, uploadedChunks }
+const finalizeUploadSession = async (req, res) → { url, privateUrl }
+
+// Presigned URL generation (S3 only, with path validation)
+const generatePresignedUrls = async (urls) → { [url]: presignedUrl }
+
+// Utilities (exported for route layer)
+const isValidPath = (urlPath) → boolean  // Path traversal protection
+const createErrorResponse = (message, code, details) → { message, code?, details? }
+const getS3ErrorStatusCode = (error) → number  // HTTP status code mapping
+```
+
+**Server-Side File Copy (S3 Native):**
+
+The `copyFile()` function uses provider-native copy operations for optimal performance:
+
+| Provider | Implementation | Performance |
+|----------|----------------|-------------|
+| S3 | `CopyObjectCommand` (server-side) | 15x faster, zero memory |
+| Local | `fs.promises.copyFile` | Kernel-level copy |
+| GCloud | Download + Upload (fallback) | Legacy behavior |
+
+```javascript
+// Single file copy
+const copyFile = async (sourceKey, destKey, { contentType }) → { url }
+
+// Parallel batch copy with concurrency control
+const copyFilesParallel = async (copies, { concurrency = 10, continueOnError = true })
+  → { succeeded: [{ sourceKey, destKey }], failed: [{ sourceKey, error }] }
+```
+
+**Benefits over download-then-upload:**
+- **15x faster**: Server-side copy, no data through backend
+- **Zero memory**: No file buffering in Node.js
+- **No timeouts**: Works for large files (>100MB)
+- **Reduced bandwidth**: No double network transfer
+
+**Error Response Format:**
+```javascript
+// Standardized across all file endpoints
+{
+  message: 'Human-readable error message',
+  code: 'ERROR_CODE',           // For programmatic handling
+  details: { ... }               // Optional additional context
+}
+```
+
+**Request Cancellation:**
+Downloads automatically abort S3 requests when client disconnects, preventing wasted bandwidth and server resources.
+
+**Provider Selection:**
+
+| Priority | Provider | Detection |
+|----------|----------|-----------|
+| 1 | `config.fileStorage.provider` | Validated `FILE_STORAGE_PROVIDER` override |
+| 2 | S3 | `S3_BUCKET` + `S3_REGION` + credentials |
+| 3 | GCloud | Validated `GC_PROJECT_ID` + `GC_CLIENT_EMAIL` + `GC_PRIVATE_KEY` |
+| 4 | Local | Default fallback |
+
+External S3/GCloud operations used by processing paths are protected by the
+shared file-storage circuit breaker. For S3, only retryable SDK/network errors
+count toward opening the breaker; expected 4xx errors do not.
+
+**Chunked Upload Flow:**
+
+```
+1. POST /api/file/upload-sessions/init
+   ← { sessionId, totalChunks }
+
+2. PUT /api/file/upload-sessions/:sessionId/chunks/:chunkIndex
+   ← { uploadedChunks: N }
+
+3. POST /api/file/upload-sessions/:sessionId/finalize
+   ← { url, privateUrl }
+```
+
+**S3 Local Cache (Atomic Writes):**
+
+When S3 is the storage provider, downloads are cached locally to reduce S3 requests and improve latency. The cache uses **atomic writes** to prevent race conditions:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Request A                    Request B (concurrent)            │
+├─────────────────────────────────────────────────────────────────┤
+│  1. Check cache → miss        1. Check cache → miss             │
+│  2. Create .downloading       2. See .downloading → skip cache  │
+│  3. Stream to .tmp file       3. Stream directly from S3        │
+│  4. Verify size matches       4. Complete                       │
+│  5. Rename .tmp → final       ↓                                 │
+│  6. Delete .downloading       Request C (later)                 │
+│     ↓                         1. Check cache → hit              │
+│                               2. Serve from cache               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Cache validation:**
+- File exists AND age < `S3_CACHE_MAX_AGE` (default: 1 hour)
+- No `.downloading` marker file (indicates download in progress)
+- Size matches `Content-Length` header (verified before rename)
+
+**Why atomic writes:**
+Without atomic writes, concurrent requests could serve truncated cache files:
+1. Request A starts downloading 12MB file, writes to cache
+2. After 2MB written, Request B checks cache - file exists, age valid
+3. Request B serves 2MB truncated file → **corrupted video/image**
+
+The atomic write pattern (write to `.tmp`, verify size, rename) prevents this.
+
+### Publish Service (`publish.ts`)
+
+Three-tier content environment publishing workflow.
+
+```javascript
+module.exports = class PublishService {
+  // Acquire project lock and run callback
+  static async withProjectPublishLock(projectId, callback)
+
+  // Copy stage content to production (blocking)
+  static async publishToProduction(projectId, currentUser, title, description)
+
+  // Copy dev content to stage (non-blocking, returns immediately)
+  static async saveToStage(projectId, currentUser)
+
+  // Generic environment copy
+  static async copyEnvironment(projectId, fromEnv, toEnv, currentUser, transaction)
+}
+```
+
+**Non-Blocking vs Blocking:**
+- `saveToStage()` - Returns immediately, copy runs in background via `setImmediate()`
+- `publishToProduction()` - Waits for entire copy operation before returning
+
+**Publishing Flow:**
+
+```
+┌─────────┐       ┌─────────┐       ┌────────────┐
+│   DEV   │──────▶│  STAGE  │──────▶│ PRODUCTION │
+│(editing)│       │(preview)│       │  (public)  │
+└─────────┘       └─────────┘       └────────────┘
+    │                  │                    │
+saveToStage()    publishToProduction()      │
+    │                  │                    │
+    └──────────────────┴────────────────────┘
+         Creates publish_event record
+```
+
+**Event Status Lifecycle:**
+1. `queued` - Event created
+2. `running` - Processing started
+3. `success` / `failed` - Completed
+
+### Search Service (`search.ts`)
+
+Global full-text search with permission filtering.
+
+```typescript
+export default class SearchService {
+  // Search across all permitted entities
+  static async search(searchQuery: string, currentUser: CurrentUser | undefined): Promise<SearchResult>
+}
+```
+
+**Searchable Tables:**
+
+| Table | Text Fields | Numeric Fields |
+|-------|-------------|----------------|
+| users | firstName, lastName, phoneNumber, email | - |
+| projects | name, slug, description, logo_url, favicon_url, og_image_url | - |
+| assets | name, cdn_url, storage_key, mime_type, checksum | size_mb, width_px, height_px, duration_sec |
+| asset_variants | cdn_url | width_px, height_px, size_mb |
+| presigned_url_requests | requested_key, mime_type, status | requested_size_mb |
+| tour_pages | source_key, name, slug, background_image_url, background_video_url, background_audio_url, ui_schema_json | sort_order |
+| project_audio_tracks | source_key, name, slug, url | volume, sort_order |
+| publish_events | error_message | pages_copied, transitions_copied, audios_copied |
+| pwa_caches | cache_version, manifest_json, asset_list_json | - |
+| access_logs | path, ip_address, user_agent | - |
+
+**Permission Check:**
+```javascript
+// Only search tables user has READ permission for
+if (!hasPermission(permissionSet, `READ_${tableName.toUpperCase()}`)) {
+  return [];
+}
+```
+
+### Projects Service (`projects.ts`)
+
+Project management with cloning capabilities and slug uniqueness validation.
+
+```javascript
+export default class ProjectsService {
+  // Normalize slug for URL safety
+  static normalizeSlug(value) → slug
+
+  // Generate unique slug with -copy suffix
+  static async generateUniqueSlug(baseSlug, transaction) → uniqueSlug
+
+  // Validate slug uniqueness before create/update (throws ValidationError if duplicate)
+  static async validateSlugUniqueness(slug, excludeId, transaction) → normalizedSlug
+
+  // Create new project (validates slug uniqueness)
+  static async create({ data, currentUser, transaction, runtimeContext }) → project
+
+  // Clone project with all assets and variants
+  static async cloneFromProject(sourceProjectId, currentUser) → clonedProject
+
+  // Update project (validates slug uniqueness if changed)
+  static async update({ id, data, currentUser, transaction, runtimeContext }) → project
+}
+```
+
+**Slug Validation:**
+- `validateSlugUniqueness()` normalizes the slug and checks for duplicates
+- Uses `excludeId` parameter to skip the current project during updates
+- Checks soft-deleted projects (`paranoid: false`) to prevent conflicts
+- Throws `ValidationError('iam.errors.slugAlreadyExists')` if duplicate found
+
+**Clone Process (Optimized with S3 Native Copy):**
+
+The clone process uses S3's native `CopyObjectCommand` for server-side file copying (15x faster than download-then-upload). Files are copied in parallel with configurable concurrency.
+
+```
+Phase A: Create cloned project record
+    ↓
+Phase B: Collect all copy operations (assets + non-reversed variants)
+    ↓
+Phase C: Execute parallel S3 copy (10 concurrent, continueOnError=true)
+    ↓
+Phase D: Build assetPathMap from copy results (failed → use original path)
+    ↓
+Phase E: Create asset/variant records, build assetIdMap (old → new asset IDs)
+    ↓
+Phase F: Copy reversed videos using asset ID mapping
+    └── Reversed videos use pattern: assets/{assetId}/reversed.mp4
+    └── Copy from old asset ID path to new asset ID path
+    ↓
+Phase G: Clone tour_pages, audio_tracks, element_defaults
+    └── Transform ui_schema_json asset paths using assetPathMap
+```
+
+**Key Implementation Details:**
+
+| Phase | Operation | Notes |
+|-------|-----------|-------|
+| B-C | Parallel file copy | Uses `FileService.copyFilesParallel()` with S3 `CopyObjectCommand` |
+| E | Asset ID mapping | Tracks `oldAssetId → newAssetId` for reversed video copying |
+| F | Reversed video copy | Separate phase because reversed videos use asset-ID-based paths, not project-ID-based |
+| G | Path transformation | `transformUiSchemaAssetPaths()` updates all asset URLs in `ui_schema_json` |
+
+**Reversed Video Storage Pattern:**
+- Primary assets: `assets/{projectId}/{uuid}.ext`
+- Reversed videos: `assets/{assetId}/reversed.mp4` (uses asset ID, not project ID)
+
+**Error Handling:**
+- Failed file copies fall back to original storage path (cloned project still functional, shares assets with source)
+- Most assets won't have reversed videos - this is expected (only navigation elements with transitions generate them)
+- Transaction rollback on DB errors; orphaned S3 files acceptable (can be cleaned later)
+
+### Roles Service (`roles.ts`)
+
+Role management service for standard CRUD, CSV bulk import, and permission assignment. The service wraps DB writes in transactions when a caller does not provide one.
+
+```typescript
+export default class RolesService {
+  static assertPublicRoleHasNoPermissions(data, existingRole)
+  static async create(options)
+  static async bulkImport(req, res)
+  static async update(options)
+  static async deleteByIds(options)
+  static async remove(options)
+}
+```
+
+**Public Role Hardening:**
+- Creating or updating a role named `Public` rejects non-empty permissions.
+- Existing role lookup is done before update so renaming a role to `Public` cannot retain assigned permissions through the service boundary.
+- This keeps customer viewer access separate from admin RBAC permissions.
+
+~~Generates offline manifests for PWA asset downloads.~~
+
+### Project Element Defaults Service (`project_element_defaults.ts`)
+
+Extended factory service with custom methods for managing project-level element defaults.
+
+```javascript
+class Project_element_defaultsService extends BaseService {
+  // Reset project default to current global default
+  static async resetToGlobal(id, options) → updated record
+
+  // Get diff between project default and global default
+  static async getDiffFromGlobal(id) → { hasChanges, diff }
+
+  // Snapshot all global defaults to a project (called on project creation)
+  static async snapshotGlobalDefaults(projectId, options) → created records
+}
+```
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `resetToGlobal(id, options)` | Resets a project element default to match the current global element type default |
+| `getDiffFromGlobal(id)` | Compares project element default with global default, returns differences |
+| `snapshotGlobalDefaults(projectId, options)` | Creates project element defaults by copying all global element type defaults |
+
+**Use Cases:**
+- **Project Creation:** `snapshotGlobalDefaults` is called to copy global defaults to new project
+- **Reset to Global:** User can reset customized project defaults back to global values
+- **Diff View:** UI can show which settings differ from global defaults
+
+---
+
+## File Storage Module (`services/file/`)
+
+### Strategy Pattern Implementation
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     BaseStorageProvider                             │
+│                    (Abstract Interface)                             │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────────┐  │
+│  │   upload    │ │  download   │ │   delete    │ │ getSignedUrl  │  │
+│  │ (abstract)  │ │ (abstract)  │ │ (abstract)  │ │  (optional)   │  │
+│  └─────────────┘ └─────────────┘ └─────────────┘ └───────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+           △                    △                    △
+           │                    │                    │
+┌──────────┴─────────┐ ┌───────┴────────┐ ┌────────┴───────┐
+│ S3StorageProvider  │ │LocalStorage    │ │(GCloud inline) │
+│                    │ │Provider        │ │                │
+│ • AWS SDK v3       │ │ • fs module    │ │ • @google-cloud│
+│ • Presigned URLs   │ │ • MIME types   │ │   /storage     │
+│ • Batch delete     │ │ • Recursive    │ │ • Resumable    │
+└────────────────────┘ └────────────────┘ └────────────────┘
+```
+
+### BaseStorageProvider Interface
+
+```typescript
+export default class BaseStorageProvider {
+  static get providerName(): string
+  upload(key, data, options): Promise<StorageUploadResult>
+  download(key): Promise<StorageDownloadResult>
+  delete(key): Promise<void>
+  deleteMany(keys): Promise<void>
+  exists(key): Promise<boolean>
+  list(prefix): Promise<string[]>
+  getSignedUrl(key, expiresIn): Promise<string | null>
+}
+```
+
+### S3StorageProvider
+
+AWS S3 implementation using SDK v3 with robust timeout, retry, and error handling.
+
+`S3StorageProvider.ts` uses official AWS SDK v3 types for client config, command inputs, signed URL generation, streaming download bodies, and `S3ServiceException` metadata. Project-specific storage contracts live in `backend/src/types/file.ts`.
+
+```javascript
+class S3StorageProvider extends BaseStorageProvider {
+  constructor({
+    bucket, region, accessKeyId, secretAccessKey, prefix,
+    connectionTimeout,   // Default: 5000ms
+    requestTimeout,      // Default: 30000ms
+    maxAttempts,         // Default: 3 (adaptive retry)
+    maxSockets,          // Default: 50 (connection pool)
+    keepAlive            // Default: true
+  })
+
+  // Static methods for error handling
+  static getErrorStatusCode(error)  // Map S3 errors to HTTP status codes
+  static isRetryableError(error)    // Check if error should be retried
+
+  // Instance methods (all support AbortSignal for cancellation)
+  buildKey(key)                            // Add prefix to key
+  async upload(key, data, { signal })      // PutObjectCommand
+  async download(key, { signal })          // GetObjectCommand
+  async copy(sourceKey, destKey, { signal, contentType })  // CopyObjectCommand (server-side)
+  async delete(key, { signal })            // DeleteObjectCommand
+  async deleteMany(keys, { signal })       // DeleteObjectsCommand (batched 1000)
+  async exists(key, { signal })            // HeadObjectCommand
+  async list(prefix, { signal })           // ListObjectsV2Command (paginated)
+  async getSignedUrl(key, expiry)          // @aws-sdk/s3-request-presigner
+  getConfig()                              // Get provider config for debugging
+  destroy()                                // Cleanup connection pool
+}
+```
+
+**S3 Error to HTTP Status Code Mapping:**
+
+| S3 Error | HTTP Status |
+|----------|-------------|
+| NoSuchKey, NotFound, NoSuchBucket | 404 |
+| AccessDenied, InvalidAccessKeyId | 403 |
+| ExpiredToken | 401 |
+| TimeoutError, RequestTimeout | 504 |
+| NetworkingError, ServiceUnavailable | 503 |
+| ThrottlingException | 429 |
+| InternalError | 500 |
+
+### LocalStorageProvider
+
+Local filesystem implementation.
+
+`LocalStorageProvider.ts` shares the same typed storage contracts as S3 while using Node filesystem and stream APIs.
+
+```javascript
+class LocalStorageProvider extends BaseStorageProvider {
+  constructor({ basePath = './uploads' })
+
+  buildPath(key)                   // path.join(basePath, key)
+  async upload(key, data)          // fs.writeFileSync / stream.pipeline
+  async download(key)              // fs.createReadStream
+  async copy(sourceKey, destKey)   // fs.promises.copyFile (kernel-level)
+  async delete(key)                // fs.unlinkSync
+  async exists(key)                // fs.existsSync
+  async list(prefix)               // fs.readdirSync (recursive)
+  getContentType(ext)              // MIME type mapping
+}
+```
+
+### UploadSessionManager
+
+Chunked upload session management for large files.
+
+`UploadSessionManager.ts` uses reusable upload-session metadata contracts from `backend/src/types/file.ts` and validates `meta.json` after parsing instead of relying on type assertions.
+
+```javascript
+class UploadSessionManager {
+  constructor({ sessionDir, ttlMs = 24h })
+
+  createSession(options)           // → sessionId (UUID)
+  readMeta(sessionId)              // → session metadata
+  writeMeta(sessionId, payload)    // Save session state
+  saveChunk(sessionId, index, data) // Save chunk file
+  chunkExists(sessionId, index)    // Check chunk exists
+  isComplete(sessionId)            // All chunks uploaded?
+  assembleChunks(sessionId, path)  // Combine chunks
+  removeSession(sessionId)         // Cleanup session
+  cleanupExpiredSessions()         // Remove stale sessions
+}
+```
+
+**Session Directory Structure:**
+```
+upload_sessions/
+└── {sessionId}/
+    ├── meta.json          # Session metadata
+    └── chunks/
+        ├── 0.part
+        ├── 1.part
+        └── N.part
+```
+
+---
+
+## Email Module (`services/email/`)
+
+### EmailSender Class
+
+Core email sending using Nodemailer.
+
+```typescript
+export default class EmailSender {
+  constructor(email: EmailTemplate)
+  async send(): Promise<EmailSendResult>
+  static get isConfigured(): boolean
+  get transportConfig(): SMTPTransport.Options
+  get from(): string
+}
+```
+
+**Configuration (`config.email`):**
+```javascript
+{
+  host: 'email-smtp.us-east-1.amazonaws.com',
+  port: 587,
+  auth: {
+    user: process.env.EMAIL_USER || '',
+    pass: process.env.EMAIL_PASS || ''
+  },
+  from: 'Tour Builder Platform <app@flatlogic.app>'
+}
+```
+
+### Email Templates
+
+| Template | Class | Fields |
+|----------|-------|--------|
+| Password Reset | `PasswordResetEmail` | to, link |
+| Email Verification | `EmailAddressVerificationEmail` | to, link |
+| User Invitation | `InvitationEmail` | to, host |
+
+**Template Pattern:**
+```typescript
+export default class PasswordResetEmail implements EmailTemplate {
+  constructor({ to, link }: LinkEmailTemplateOptions) {}
+
+  get subject(): string {
+    return getNotification('emails.passwordReset.subject', getNotification('app.title'));
+  }
+
+  async html(): Promise<string> {
+    const template = await fs.readFile(templatePath, 'utf8');
+    return template
+      .replace(/{appTitle}/g, appTitle)
+      .replace(/{resetUrl}/g, this.link)
+      .replace(/{accountName}/g, this.to);
+  }
+};
+```
+
+---
+
+## Notifications Module (`services/notifications/`)
+
+### Error Classes
+
+**ValidationError (400 Bad Request):**
+```javascript
+class ValidationError extends Error {
+  constructor(messageCode) {
+    const message = isNotification(messageCode)
+      ? getNotification(messageCode)
+      : getNotification('errors.validation.message');
+    super(message);
+    this.code = 400;
+  }
+}
+```
+
+**ForbiddenError (403 Forbidden):**
+```javascript
+class ForbiddenError extends Error {
+  constructor(messageCode) {
+    const message = isNotification(messageCode)
+      ? getNotification(messageCode)
+      : getNotification('errors.forbidden.message');
+    super(message);
+    this.code = 403;
+  }
+}
+```
+
+### Notification Catalog (`list.js`)
+
+Centralized error messages and i18n strings.
+
+```javascript
+const errors = {
+  app: {
+    title: 'Tour Builder Platform',
+  },
+  auth: {
+    userDisabled: 'Your account is disabled',
+    forbidden: 'Forbidden',
+    unauthorized: 'Unauthorized',
+    userNotFound: "Sorry, we don't recognize your credentials",
+    wrongPassword: "Sorry, we don't recognize your credentials",
+    // ...
+  },
+  iam: {
+    errors: {
+      userAlreadyExists: 'User with this email already exists',
+      userNotFound: 'User not found',
+      // ...
+    }
+  },
+  emails: {
+    invitation: {
+      subject: "You've been invited to {0}",
+      body: "..."
+    },
+    // ...
+  }
+};
+```
+
+### Helper Functions
+
+```javascript
+// Get notification with parameter substitution
+getNotification('emails.invitation.subject', 'Tour Builder')
+// → "You've been invited to Tour Builder"
+
+// Check if key exists in catalog
+isNotification('auth.userNotFound') // → true
+isNotification('custom.message')    // → false
+```
+
+---
+
+## Transaction Patterns
+
+### Standard Transaction Pattern
+
+All services use consistent transaction handling:
+
+```javascript
+static async create({ data, currentUser, transaction: externalTransaction, runtimeContext }) {
+  const transaction = externalTransaction || await db.sequelize.transaction();
+  const ownsTransaction = !externalTransaction;
+  try {
+    const record = await DBApi.create({ data, currentUser, transaction, runtimeContext });
+    if (ownsTransaction) await transaction.commit();
+    return record;
+  } catch (error) {
+    if (ownsTransaction) await transaction.rollback();
+    throw error;
+  }
+}
+```
+
+### Lock Pattern (Publish Service)
+
+```javascript
+static async withProjectPublishLock(projectId, callback) {
+  return db.sequelize.transaction(async (transaction) => {
+    // Acquire row lock
+    const project = await db.projects.findByPk(projectId, {
+      transaction,
+      lock: transaction.LOCK.UPDATE,
+    });
+
+    // Check for concurrent operations
+    const runningEvent = await db.publish_events.findOne({
+      where: { projectId, status: EVENT_STATUS.RUNNING },
+      transaction,
+      lock: transaction.LOCK.UPDATE,
+    });
+
+    if (runningEvent) {
+      throw new Error('Publish is already running for this project');
+    }
+
+    return callback(transaction);
+  });
+}
+```
+
+---
+
+## Dependencies
+
+### External Packages
+
+| Package | Usage |
+|---------|-------|
+| `bcrypt` | Password hashing |
+| `nodemailer` | Email sending |
+| `csv-parser` | CSV import parsing |
+| `axios` | External API calls (widgets) |
+| `uuid` | Upload session IDs |
+| `@aws-sdk/client-s3` | S3 operations |
+| `@aws-sdk/s3-request-presigner` | Presigned URLs |
+| `@google-cloud/storage` | GCloud storage |
+| `lodash/get` | Deep object access |
+
+### Internal Dependencies
+
+| Module | Services Using |
+|--------|---------------|
+| `db/models` | All services (transaction) |
+| `db/api/*` | All entity services |
+| `factories/service.factory` | 9 factory services |
+| `config` | auth, file, users, roles |
+| `helpers` | auth (jwtSign) |
+
+---
+
+## Service Relationships
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         Service Graph                               │
+│                                                                     │
+│  ┌──────────┐                                                       │
+│  │   auth   │◄────────────────────┐                                 │
+│  └────┬─────┘                     │                                 │
+│       │ uses                      │ sends invitations               │
+│       ▼                           │                                 │
+│  ┌──────────┐     ┌───────────┐   │                                 │
+│  │  users   │────▶│  email    │───┘                                 │
+│  │ (DBApi)  │     └───────────┘                                     │
+│  └──────────┘           │                                           │
+│                         │ uses templates                            │
+│                         ▼                                           │
+│                  ┌─────────────────┐                                │
+│                  │  notifications  │                                │
+│                  │ (error catalog) │                                │
+│                  └─────────────────┘                                │
+│                         ▲                                           │
+│                         │ throws errors                             │
+│                         │                                           │
+│  ┌──────────┐     ┌─────┴─────┐     ┌──────────┐                    │
+│  │ projects │     │  publish  │     │  search  │                    │
+│  │ (clone)  │     │ (env copy)│     │(fulltext)│                    │
+│  └──────────┘     └───────────┘     └──────────┘                    │
+│                                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │                      File Service                            │   │
+│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐  │   │
+│  │  │ S3Provider   │ │LocalProvider │ │UploadSessionManager  │  │   │
+│  │  └──────────────┘ └──────────────┘ └──────────────────────┘  │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Service | Description |
+|----------|---------|-------------|
+| `FILE_STORAGE_PROVIDER` | file | Force provider ('s3', 'gcloud', 'local') |
+| `AWS_S3_BUCKET` | file | S3 bucket name |
+| `AWS_S3_REGION` | file | AWS region (default: us-east-1) |
+| `AWS_ACCESS_KEY_ID` | file | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | file | AWS secret key |
+| `AWS_S3_PREFIX` | file | Key prefix |
+| `AWS_S3_CONNECTION_TIMEOUT` | file | S3 connection timeout in ms (default: 5000) |
+| `AWS_S3_REQUEST_TIMEOUT` | file | S3 request timeout in ms (default: 30000) |
+| `AWS_S3_MAX_ATTEMPTS` | file | S3 retry attempts (default: 3) |
+| `AWS_S3_MAX_SOCKETS` | file | S3 connection pool size (default: 50) |
+| `AWS_S3_KEEP_ALIVE` | file | Enable HTTP keep-alive (default: true) |
+| `AWS_S3_PRESIGN_EXPIRY` | file | Presigned URL expiry in seconds (default: 3600) |
+| `GC_PROJECT_ID` | file | GCloud project |
+| `GC_CLIENT_EMAIL` | file | GCloud service account |
+| `GC_PRIVATE_KEY` | file | GCloud private key |
+| `FFMPEG_REVERSE_TIMEOUT_MS` | videoProcessing | Reverse-video hard timeout in ms (default: 600000) |
+| `FFPROBE_TIMEOUT_MS` | videoProcessing | Metadata probe timeout in ms (default: 30000) |
+| `FFMPEG_BREAKER_FAILURE_THRESHOLD` | videoProcessing | Failures before FFmpeg breaker opens (default: 3) |
+| `FFMPEG_BREAKER_COOLDOWN_MS` | videoProcessing | FFmpeg breaker cooldown in ms (default: 120000) |
+| `FFMPEG_BREAKER_SUCCESS_THRESHOLD` | videoProcessing | Half-open successes required to close FFmpeg breaker (default: 1) |
+| `FILE_STORAGE_BREAKER_FAILURE_THRESHOLD` | file | Failures before storage breaker opens (default: 5) |
+| `FILE_STORAGE_BREAKER_COOLDOWN_MS` | file | Storage breaker cooldown in ms (default: 30000) |
+| `FILE_STORAGE_BREAKER_SUCCESS_THRESHOLD` | file | Half-open successes required to close storage breaker (default: 2) |
+| `EMAIL_USER` | email | SMTP username |
+| `EMAIL_PASS` | email | SMTP password |
+
+### Config References
+
+```javascript
+// config.ts
+module.exports = {
+  bcrypt: { saltRounds: 12 },
+  email: { host, port, auth, from },
+  s3: {
+    bucket,
+    region,
+    accessKeyId,
+    secretAccessKey,
+    prefix,
+    // Timeout/retry configuration
+    connectionTimeout,     // 5000ms default
+    requestTimeout,        // 30000ms default
+    maxAttempts,           // 3 retries with adaptive backoff
+    // Connection pool
+    maxSockets,            // 50 concurrent connections
+    keepAlive,             // HTTP keep-alive enabled
+    // Presigned URLs
+    presignExpirySeconds,  // 3600 (1 hour) default
+  },
+  gcloud: { bucket, hash },
+  uploadDir: './uploads',
+  flHost: 'https://flatlogic.host',  // Widget service
+  project_uuid: '...',
+};
+```
+
+---
+
+## Testing Guidelines
+
+### Unit Testing Services
+
+```javascript
+// Mock transaction
+jest.mock('../db/models', () => ({
+  sequelize: {
+    transaction: jest.fn(() => ({
+      commit: jest.fn(),
+      rollback: jest.fn(),
+    })),
+  },
+}));
+
+// Mock DB API
+jest.mock('../db/api/assets');
+
+describe('AssetsService', () => {
+  it('should create asset with transaction', async () => {
+    const result = await AssetsService.create({
+      data: mockData,
+      currentUser: mockUser,
+    });
+    expect(transaction.commit).toHaveBeenCalled();
+  });
+});
+```
+
+### Integration Testing
+
+```javascript
+describe('PublishService', () => {
+  it('should copy dev to stage', async () => {
+    // Create test project with pages
+    const project = await createTestProject();
+    await createTestPages(project.id, 'dev');
+
+    // Publish to stage
+    const result = await PublishService.saveToStage(project.id, mockUser);
+
+    // Verify stage pages created
+    const stagePages = await findPages(project.id, 'stage');
+    expect(stagePages.length).toBe(result.summary.pages_copied);
+  });
+});
+```
+
+---
+
+## Best Practices
+
+### 1. Transaction Handling
+- Always wrap multi-step operations in transactions
+- Use try/catch/rollback pattern consistently
+- Pass transaction to all DB API calls
+
+### 2. Error Handling
+- Use `ValidationError` for client errors (400)
+- Use `ForbiddenError` for authorization failures (403)
+- Use notification catalog for consistent messages
+
+### 3. Service Design
+- Keep services focused on business logic
+- Delegate DB operations to DB API layer
+- Use factories for simple CRUD services
+
+### 4. File Operations
+- Use Strategy Pattern for multi-provider support
+- Implement chunked uploads for large files
+- Clean up sessions on completion/failure
+
+---
+
+## Related Documentation
+
+- [Backend Architecture](../backend-architecture.md) - Overall backend design
+- [Database Schema](../database-schema.md) - Data models
+- [API Endpoints](../api-endpoints.md) - REST API reference
+- [Auth Module](./auth.md) - Authentication details
+- [Routes Module](./routes.md) - Route implementations
diff --git a/backend/docs/modules/utilities.md b/backend/docs/modules/utilities.md
new file mode 100644
index 0000000..fd3001e
--- /dev/null
+++ b/backend/docs/modules/utilities.md
@@ -0,0 +1,857 @@
+# Utilities Module
+
+## Overview
+
+The Utilities module provides centralized helper functions, error handling, logging, environment validation, and i18n message management. Utilities are organized across several locations based on their domain.
+
+**Locations:**
+- `backend/src/utils/` - Core utilities (errors, logging, env validation, request context)
+- `backend/src/helpers.ts` - Request helpers (async wrapper, error handler, JWT)
+- `backend/src/db/utils.ts` - Database utilities
+- `backend/src/services/notifications/` - i18n messages and legacy error classes
+
+---
+
+## Architecture
+
+```
+backend/src/
+├── utils/
+│   ├── index.ts              # Re-exports
+│   ├── errors.ts             # Error classes
+│   ├── logger.ts             # Pino logging
+│   ├── request-context.ts    # Request-scoped context storage
+│   └── env-validation.ts     # Joi env schema
+├── helpers.ts                # Request helpers
+├── db/
+│   └── utils.ts              # DB utilities
+└── services/notifications/
+    ├── list.ts               # i18n message catalog
+    ├── helpers.ts            # Message formatting
+    └── errors/
+        ├── forbidden.ts      # ForbiddenError
+        └── validation.ts     # ValidationError
+```
+
+---
+
+## Core Utilities (`utils/`)
+
+### Error Classes (`utils/errors.js`)
+
+Modern error hierarchy for consistent HTTP error responses.
+
+```javascript
+class AppError extends Error {
+  constructor(message, statusCode = 500, details = null) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.isOperational = true;  // Distinguishes from programming errors
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+```
+
+**Error Types:**
+
+| Class | Status Code | Default Message | Usage |
+|-------|-------------|-----------------|-------|
+| `AppError` | 500 | (custom) | Base class |
+| `NotFoundError` | 404 | `{resource} not found` | Missing resources |
+| `ValidationError` | 400 | (custom) | Invalid input |
+| `ForbiddenError` | 403 | `Access denied` | Permission denied |
+| `UnauthorizedError` | 401 | `Unauthorized` | Auth required |
+| `ConflictError` | 409 | `Resource conflict` | Duplicate resources |
+
+**Usage:**
+```javascript
+const { NotFoundError, ValidationError, ForbiddenError } = require('./utils');
+
+// In route handler
+if (!user) {
+  throw new NotFoundError('User');
+}
+
+const currentUser = getCurrentUser(req);
+if (!currentUser) {
+  throw new ForbiddenError();
+}
+
+if (errors.length > 0) {
+  throw new ValidationError('Invalid data', errors);
+}
+```
+
+---
+
+### Structured Logging (`utils/logger.ts`)
+
+Pino-based logging with request correlation and environment-aware formatting.
+Logger initialization is a bootstrap exception where direct `process.env`
+access is allowed; runtime services should use `config.ts` instead.
+
+```javascript
+const pino = require('pino');
+const crypto = require('crypto');
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport: isDevelopment
+    ? { target: 'pino-pretty', options: { colorize: true } }
+    : undefined,
+  base: {
+    service: 'tour-builder-api',
+    env: process.env.NODE_ENV || 'development',
+  },
+});
+```
+
+**Log Levels:**
+- `fatal` - Unrecoverable errors
+- `error` - Errors requiring attention
+- `warn` - Warning conditions (400-499 responses)
+- `info` - Normal operations (default)
+- `debug` - Detailed debugging
+- `trace` - Very detailed tracing
+
+**Process-Level Failure Logging:**
+
+`registerProcessErrorHandlers()` is called from `src/index.ts` during backend
+startup. It installs handlers for `uncaughtException` and `unhandledRejection`,
+logs them through Pino at `fatal`, normalizes non-`Error` rejection reasons into
+`Error` instances with `cause`, flushes Pino, and then exits with status `1`.
+These failures happen outside the Express request lifecycle, so route error
+middleware cannot catch them.
+
+```typescript
+registerProcessErrorHandlers();
+
+process.on('unhandledRejection', (reason) => {
+  logger.fatal(
+    { err: normalizeLoggedError(reason) },
+    'Unhandled promise rejection, shutting down process',
+  );
+  exitAfterLogging();
+});
+```
+
+**Request Logger Middleware:**
+```javascript
+function requestLogger(req, res, next) {
+  // Generate or use existing request ID
+  const requestId = req.headers['x-request-id'] || crypto.randomUUID();
+
+  // Store child logger in request context
+  setRequestLogger(req, logger.child({ requestId }));
+  setRequestId(req, requestId);
+  res.setHeader('X-Request-Id', requestId);
+
+  const start = Date.now();
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    const logData = {
+      method: req.method,
+      url: req.originalUrl || req.url,
+      status: res.statusCode,
+      duration,
+      userAgent: req.headers['user-agent'],
+    };
+
+    // Log level based on status code
+    if (res.statusCode >= 500) {
+      getRequestLogger(req)?.error(logData, 'Request completed with server error');
+    } else if (res.statusCode >= 400) {
+      getRequestLogger(req)?.warn(logData, 'Request completed with client error');
+    } else {
+      getRequestLogger(req)?.info(logData, 'Request completed');
+    }
+  });
+
+  next();
+}
+```
+
+**Log Output Examples:**
+
+Development (pino-pretty):
+```
+[12:34:56.789] INFO (tour-builder-api): Request completed
+    requestId: "abc-123"
+    method: "GET"
+    url: "/api/users"
+    status: 200
+    duration: 45
+```
+
+Production (JSON):
+```json
+{"level":30,"time":1711723456789,"service":"tour-builder-api","env":"production","requestId":"abc-123","method":"GET","url":"/api/users","status":200,"duration":45,"msg":"Request completed"}
+```
+
+**Usage:**
+```javascript
+const { logger, requestLogger } = require('./utils/logger');
+
+// App setup
+app.use(requestLogger);
+
+// Manual logging
+logger.info({ userId: user.id }, 'User logged in');
+logger.error({ err }, 'Database connection failed');
+
+// Request-scoped logging (in routes)
+getRequestLogger(req)?.info({ data }, 'Processing request');
+```
+
+---
+
+### Request Context (`utils/request-context.ts`)
+
+Request-scoped data is stored outside the Express `Request` object through a
+`WeakMap<Request, AppRequestContext>`. Do not add global
+`Express.Request` augmentation for project fields such as `currentUser`,
+`runtimeContext`, `log`, or runtime-public flags. Middleware should write with
+`setCurrentUser`, `setRuntimeContext`, `setRequestLogger`, and related helpers;
+routes/services should read through `getCurrentUser`, `getRuntimeContext`,
+`getRequestLogger`, and `getRouteServiceContext`.
+
+### Environment Validation (`utils/env-validation.ts`)
+
+Joi-based validation ensuring all required environment variables are present with correct types.
+
+**Schema Definition:**
+```javascript
+const Joi = require('joi');
+
+const envSchema = Joi.object({
+  // Server
+  NODE_ENV: Joi.string()
+    .valid('development', 'test', 'production', 'dev_stage')
+    .default('development'),
+  PORT: Joi.number().default(8080),
+
+  // Database
+  DB_HOST: Joi.string().default('localhost'),
+  DB_PORT: Joi.number().default(5432),
+  DB_NAME: Joi.string().default('db_tour_builder_platform'),
+  DB_USER: Joi.string().default('postgres'),
+  DB_PASS: Joi.string().allow('').default(''),
+
+  // Authentication
+  SECRET_KEY: Joi.string()
+    .min(16)
+    .default('88dbeaf8-e906-405e-9e41-c3baadeda5c6'),
+  ADMIN_PASS: Joi.string().default('88dbeaf8'),
+  USER_PASS: Joi.string().default('c3baadeda5c6'),
+  ADMIN_EMAIL: Joi.string().email().default('admin@flatlogic.com'),
+
+  // OAuth
+  GOOGLE_CLIENT_ID: Joi.string().allow('').default(''),
+  GOOGLE_CLIENT_SECRET: Joi.string().allow('').default(''),
+  MS_CLIENT_ID: Joi.string().allow('').default(''),
+  MS_CLIENT_SECRET: Joi.string().allow('').default(''),
+
+  // AWS S3
+  AWS_ACCESS_KEY_ID: Joi.string().allow('').default(''),
+  AWS_SECRET_ACCESS_KEY: Joi.string().allow('').default(''),
+  AWS_S3_BUCKET: Joi.string().allow('').default(''),
+  AWS_S3_REGION: Joi.string().default('us-east-1'),
+  AWS_S3_PREFIX: Joi.string().default('afeefb9d49f5b7977577876b99532ac7'),
+
+  // Email
+  EMAIL_USER: Joi.string().allow('').default(''),
+  EMAIL_PASS: Joi.string().allow('').default(''),
+  EMAIL_TLS_REJECT_UNAUTHORIZED: Joi.string()
+    .valid('true', 'false')
+    .default('true'),
+
+  // External APIs
+  PEXELS_KEY: Joi.string().allow('').default(''),
+
+  // Logging
+  LOG_LEVEL: Joi.string()
+    .valid('fatal', 'error', 'warn', 'info', 'debug', 'trace')
+    .default('info'),
+}).unknown(true);  // Allow additional env vars
+```
+
+**Validation Function:**
+```javascript
+function validateEnv() {
+  const { error, value } = envSchema.validate(process.env, {
+    abortEarly: false,     // Report all errors
+    stripUnknown: false,   // Keep unknown vars
+  });
+
+  if (error) {
+    const messages = error.details.map((d) => `  - ${d.message}`);
+    logger.error({ errors: messages }, 'Environment validation failed');
+
+    // Strict in production, lenient in development
+    if (process.env.NODE_ENV === 'production') {
+      process.exit(1);
+    } else {
+      logger.warn('Continuing with default values in non-production mode');
+    }
+  }
+
+  return value;  // Returns validated/defaulted values
+}
+```
+
+**Environment Variable Categories:**
+
+| Category | Variables | Required |
+|----------|-----------|----------|
+| **Server** | `NODE_ENV`, `PORT` | Defaults |
+| **Database** | `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASS` | Defaults |
+| **Auth** | `SECRET_KEY`, `ADMIN_PASS`, `USER_PASS`, `ADMIN_EMAIL` | Defaults |
+| **OAuth** | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `MS_CLIENT_ID`, `MS_CLIENT_SECRET` | Optional |
+| **AWS S3** | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_S3_BUCKET`, `AWS_S3_REGION`, `AWS_S3_PREFIX` | Optional |
+| **Email** | `EMAIL_USER`, `EMAIL_PASS`, `EMAIL_TLS_REJECT_UNAUTHORIZED` | Optional |
+| **External APIs** | `PEXELS_KEY` | Optional |
+| **Logging** | `LOG_LEVEL` | Defaults |
+
+---
+
+### Index Re-exports (`utils/index.js`)
+
+Convenient re-export of utilities:
+
+```javascript
+module.exports = {
+  ...require('./errors'),
+  ...require('./logger'),
+  envValidation: require('./env-validation'),
+};
+```
+
+**Exported:**
+- `AppError`, `NotFoundError`, `ValidationError`, `ForbiddenError`, `UnauthorizedError`, `ConflictError`
+- `logger`, `requestLogger`, `registerProcessErrorHandlers`,
+  `exitAfterLogging`,
+  `normalizeLoggedError`
+- `envValidation.validateEnv`, `envValidation.envSchema`
+
+---
+
+## Request Helpers (`helpers.js`)
+
+Core helper class for Express route handling.
+
+```javascript
+const jwt = require('jsonwebtoken');
+const config = require('./config');
+
+module.exports = class Helpers {
+  // Wrap async route handlers to catch errors
+  static wrapAsync(fn) {
+    return function (req, res, next) {
+      fn(req, res, next).catch(next);
+    };
+  }
+
+  // Centralized error response handler
+  static commonErrorHandler(error, req, res, _next) {
+    const statusCode = error.code || error.status;
+
+    if ([400, 401, 403, 404, 409, 422].includes(statusCode)) {
+      return res.status(statusCode).send(error.message);
+    }
+
+    console.error(error);
+    return res.status(500).send('Internal server error');
+  }
+
+  // Generate JWT token
+  static jwtSign(data) {
+    return jwt.sign(data, config.secret_key, { expiresIn: '6h' });
+  }
+
+  // Validate UUID v4 format
+  static isUuidV4(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+      value,
+    );
+  }
+};
+```
+
+**Functions:**
+
+| Function | Purpose | Usage |
+|----------|---------|-------|
+| `wrapAsync(fn)` | Wraps async handlers to propagate errors | All async route handlers |
+| `commonErrorHandler(err, req, res, next)` | Standardizes error responses | Route error middleware |
+| `jwtSign(data)` | Creates JWT with 6h expiry | Auth service |
+| `isUuidV4(value)` | Validates UUID v4 format | Route parameter validation |
+
+## Request Validation
+
+Request validation is centralized in:
+
+- `src/middlewares/validate-request.ts` - Joi middleware for `params`, `query`, and `body`
+- `src/validators/request-schemas.ts` - shared schemas for CRUD, auth, users, projects, tour pages, publish, and file upload endpoints
+
+New external routes must validate all incoming `params`, `query`, and `body` before calling services. Factory CRUD routes use default schemas automatically and can override them through the `validation` option.
+
+```typescript
+import { validateRequest } from '../middlewares/validate-request.ts';
+import { publish as publishSchemas } from '../validators/request-schemas.ts';
+
+router.post(
+  '/save-to-stage',
+  validateRequest(publishSchemas.saveToStage),
+  wrapAsync(async (req, res) => {
+    const result = await PublishService.saveToStage(
+      req.body.projectId,
+      getCurrentUser(req),
+    );
+    res.status(200).json(result);
+  }),
+);
+```
+
+Request validation errors return JSON:
+
+```json
+{
+  "error": "Invalid request",
+  "details": [
+    {
+      "path": "projectId",
+      "message": "\"projectId\" must be a valid GUID",
+      "type": "string.guid"
+    }
+  ]
+}
+```
+
+Service/domain `ValidationError` responses keep the legacy plain-text format unless they are raised by request validation middleware.
+
+**Usage Pattern:**
+```javascript
+const { wrapAsync, commonErrorHandler, isUuidV4 } = require('../helpers');
+
+// Async route handler
+router.get('/users/:id', wrapAsync(async (req, res) => {
+  if (!isUuidV4(req.params.id)) {
+    return res.status(400).send('Invalid ID format');
+  }
+
+  const user = await UserService.findOne(req.params.id);
+  res.json(user);
+}));
+
+// Register error handler at end of router
+router.use('/', commonErrorHandler);
+```
+
+---
+
+## Database Utilities (`db/utils.js`)
+
+Utilities specific to Sequelize database operations, including clean UUID validation functions.
+
+```javascript
+const validator = require('validator');
+const { v4: uuidv4 } = require('uuid');
+const Sequelize = require('./models').Sequelize;
+
+module.exports = class Utils {
+  // Check if value is a valid UUID
+  static isValidUuid(value) {
+    return Boolean(value && validator.isUUID(String(value)));
+  }
+
+  // Generate a new UUID v4
+  static generateUuid() {
+    return uuidv4();
+  }
+
+  // Filter array to only valid UUIDs
+  static filterValidUuids(values) {
+    return values.filter((v) => this.isValidUuid(v));
+  }
+
+  // Case-insensitive LIKE query
+  static ilike(model, column, value) {
+    return Sequelize.where(
+      Sequelize.fn('lower', Sequelize.col(`${model}.${column}`)),
+      { [Sequelize.Op.like]: `%${value}%`.toLowerCase() },
+    );
+  }
+};
+```
+
+**Functions:**
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `isValidUuid(value)` | Check if value is a valid UUID | `boolean` |
+| `generateUuid()` | Generate a new UUID v4 | `string` |
+| `filterValidUuids(values)` | Filter array to only valid UUIDs | `string[]` |
+| `ilike(model, column, value)` | Case-insensitive LIKE search | Sequelize where clause |
+
+**UUID Validation Behavior:**
+- Invalid single ID filter (`?id=xxx`) → returns `{ rows: [], count: 0 }` immediately
+- Invalid UUIDs in relation filters (`?project=uuid|name`) → filtered out for ID search, kept for text search
+- Invalid UUID field filter (`?projectId=xxx`) → returns `{ rows: [], count: 0 }` immediately
+
+**Usage in DB API:**
+```javascript
+const Utils = require('../utils');
+
+class GenericDBApi {
+  async findAll(filter = {}, options = {}) {
+    // Single ID validation
+    if (filter.id) {
+      if (!Utils.isValidUuid(filter.id)) {
+        return { rows: [], count: 0 };
+      }
+      where.id = filter.id;
+    }
+
+    // Relation filter with mixed UUID/text search
+    for (const rel of this.RELATION_FILTERS) {
+      if (filter[rel.filterKey]) {
+        const searchTerms = filter[rel.filterKey].split('|');
+        const validUuids = Utils.filterValidUuids(searchTerms);
+
+        // UUID search: only valid UUIDs
+        // Text search: all terms
+      }
+    }
+  }
+
+  async findAllAutocomplete({ query, limit, offset }) {
+    const orConditions = [
+      Utils.ilike(this.TABLE_NAME, this.AUTOCOMPLETE_FIELD, query),
+    ];
+
+    // Only add UUID search if query is a valid UUID
+    if (Utils.isValidUuid(query)) {
+      orConditions.unshift({ id: query });
+    }
+
+    // ...
+  }
+}
+```
+
+---
+
+## Notifications Module (`services/notifications/`)
+
+i18n message management and legacy error classes.
+
+### Message Catalog (`list.js`)
+
+Centralized message definitions with placeholders:
+
+```javascript
+const errors = {
+  app: {
+    title: 'Tour Builder Platform',
+  },
+
+  auth: {
+    userDisabled: 'Your account is disabled',
+    forbidden: 'Forbidden',
+    unauthorized: 'Unauthorized',
+    userNotFound: `Sorry, we don't recognize your credentials`,
+    wrongPassword: `Sorry, we don't recognize your credentials`,
+    weakPassword: 'This password is too weak',
+    emailAlreadyInUse: 'Email is already in use',
+    invalidEmail: 'Please provide a valid email',
+    passwordReset: {
+      invalidToken: 'Password reset link is invalid or has expired',
+      error: `Email not recognized`,
+    },
+    passwordUpdate: {
+      samePassword: `You can't use the same password. Please create new password`,
+    },
+    userNotVerified: `Sorry, your email has not been verified yet`,
+    emailAddressVerificationEmail: {
+      invalidToken: 'Email verification link is invalid or has expired',
+      error: `Email not recognized`,
+    },
+  },
+
+  iam: {
+    errors: {
+      userAlreadyExists: 'User with this email already exists',
+      userNotFound: 'User not found',
+      disablingHimself: `You can't disable yourself`,
+      revokingOwnPermission: `You can't revoke your own owner permission`,
+      deletingHimself: `You can't delete yourself`,
+      emailRequired: 'Email is required',
+    },
+  },
+
+  importer: {
+    errors: {
+      invalidFileEmpty: 'The file is empty',
+      invalidFileExcel: 'Only excel (.xlsx) files are allowed',
+      invalidFileUpload: 'Invalid file. Make sure you are using the last version of the template.',
+      importHashRequired: 'Import hash is required',
+      importHashExistent: 'Data has already been imported',
+      userEmailMissing: 'Some items in the CSV do not have an email',
+    },
+  },
+
+  errors: {
+    forbidden: { message: 'Forbidden' },
+    validation: { message: 'An error occurred' },
+    searchQueryRequired: { message: 'Search query is required' },
+  },
+
+  emails: {
+    invitation: {
+      subject: `You've been invited to {0}`,
+      body: `<p>Hello,</p><p>You've been invited to {0}...</p>`,
+    },
+    emailAddressVerification: {
+      subject: `Verify your email for {0}`,
+      body: `<p>Hello,</p><p>Follow this link to verify...</p>`,
+    },
+    passwordReset: {
+      subject: `Reset your password for {0}`,
+      body: `<p>Hello,</p><p>Follow this link to reset...</p>`,
+    },
+  },
+};
+```
+
+**Message Categories:**
+
+| Category | Purpose | Examples |
+|----------|---------|----------|
+| `app` | Application metadata | `app.title` |
+| `auth` | Authentication errors | `auth.userDisabled`, `auth.wrongPassword` |
+| `iam` | User management errors | `iam.errors.userAlreadyExists` |
+| `importer` | Import/export errors | `importer.errors.invalidFileEmpty` |
+| `errors` | Generic errors | `errors.forbidden.message` |
+| `emails` | Email templates | `emails.invitation.subject` |
+
+---
+
+### Message Helpers (`helpers.js`)
+
+Functions for message formatting and lookup:
+
+```javascript
+const _get = require('lodash/get');
+const errors = require('./list');
+
+// Format message with placeholder substitution
+function format(message, args) {
+  if (!message) return null;
+  return message.replace(/{(\d+)}/g, function (match, number) {
+    return typeof args[number] != 'undefined' ? args[number] : match;
+  });
+}
+
+// Check if key exists in catalog
+const isNotification = (key) => {
+  const message = _get(errors, key);
+  return !!message;
+};
+
+// Get formatted message by key
+const getNotification = (key, ...args) => {
+  const message = _get(errors, key);
+  if (!message) return key;
+  return format(message, args);
+};
+```
+
+**Usage:**
+```javascript
+const { getNotification, isNotification } = require('./helpers');
+
+// Lookup message
+getNotification('auth.userDisabled');
+// → 'Your account is disabled'
+
+// Format with placeholders
+getNotification('emails.invitation.subject', 'Tour Builder');
+// → "You've been invited to Tour Builder"
+
+// Check existence
+isNotification('auth.userDisabled');  // → true
+isNotification('unknown.key');        // → false
+```
+
+---
+
+### Legacy Error Classes (`errors/`)
+
+i18n-aware error classes (legacy pattern, prefer `utils/errors.js`):
+
+**ForbiddenError:**
+```javascript
+const { getNotification, isNotification } = require('../helpers');
+
+module.exports = class ForbiddenError extends Error {
+  constructor(messageCode) {
+    let message;
+
+    if (messageCode && isNotification(messageCode)) {
+      message = getNotification(messageCode);
+    }
+
+    message = message || getNotification('errors.forbidden.message');
+
+    super(message);
+    this.code = 403;
+  }
+};
+```
+
+**ValidationError:**
+```javascript
+module.exports = class ValidationError extends Error {
+  constructor(messageCode) {
+    let message;
+
+    if (messageCode && isNotification(messageCode)) {
+      message = getNotification(messageCode);
+    }
+
+    message = message || getNotification('errors.validation.message');
+
+    super(message);
+    this.code = 400;
+  }
+};
+```
+
+**Usage:**
+```javascript
+const ForbiddenError = require('./services/notifications/errors/forbidden');
+const ValidationError = require('./services/notifications/errors/validation');
+
+// With i18n key
+throw new ForbiddenError('auth.forbidden');
+throw new ValidationError('iam.errors.emailRequired');
+
+// With default message
+throw new ForbiddenError();  // → 'Forbidden'
+throw new ValidationError(); // → 'An error occurred'
+```
+
+---
+
+## Error Handling Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Route Handler                           │
+│                                                             │
+│   router.get('/users/:id', wrapAsync(async (req, res) => {  │
+│     throw new NotFoundError('User');                        │
+│   }));                                                      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                    wrapAsync catches
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  commonErrorHandler                         │
+│                                                             │
+│   - Checks error.code or error.status                       │
+│   - Known codes (400-422): returns error.message            │
+│   - Unknown: returns 'Internal server error'                │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    HTTP Response                            │
+│                                                             │
+│   HTTP/1.1 404 Not Found                                    │
+│   Content-Type: text/plain                                  │
+│                                                             │
+│   User not found                                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Usage Summary
+
+### Recommended Imports
+
+```javascript
+// Modern error classes
+const { NotFoundError, ValidationError, ForbiddenError } = require('./utils');
+
+// Logging
+const { logger, requestLogger } = require('./utils/logger');
+
+// Request helpers
+const { wrapAsync, commonErrorHandler, isUuidV4 } = require('./helpers');
+
+// Database utilities
+const Utils = require('./db/utils');
+
+// i18n messages
+const { getNotification } = require('./services/notifications/helpers');
+```
+
+### Error Class Selection
+
+| Scenario | Recommended Class |
+|----------|-------------------|
+| Resource not found | `NotFoundError` from `utils/errors.js` |
+| Invalid input | `ValidationError` from `utils/errors.js` |
+| Permission denied | `ForbiddenError` from `utils/errors.js` |
+| Auth required | `UnauthorizedError` from `utils/errors.js` |
+| Duplicate resource | `ConflictError` from `utils/errors.js` |
+| i18n error message | Legacy classes from `notifications/errors/` |
+
+---
+
+## Environment Variables Reference
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `NODE_ENV` | string | `development` | `development`, `test`, `production`, `dev_stage` |
+| `PORT` | number | `8080` | Server port |
+| `DB_HOST` | string | `localhost` | PostgreSQL host |
+| `DB_PORT` | number | `5432` | PostgreSQL port |
+| `DB_NAME` | string | `db_tour_builder_platform` | Database name |
+| `DB_USER` | string | `postgres` | Database user |
+| `DB_PASS` | string | `` | Database password |
+| `SECRET_KEY` | string | UUID | JWT signing key (min 16 chars) |
+| `ADMIN_EMAIL` | email | `admin@flatlogic.com` | Admin account email |
+| `ADMIN_PASS` | string | `88dbeaf8` | Admin account password |
+| `USER_PASS` | string | `c3baadeda5c6` | Default user password |
+| `GOOGLE_CLIENT_ID` | string | `` | Google OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | string | `` | Google OAuth client secret |
+| `MS_CLIENT_ID` | string | `` | Microsoft OAuth client ID |
+| `MS_CLIENT_SECRET` | string | `` | Microsoft OAuth client secret |
+| `AWS_ACCESS_KEY_ID` | string | `` | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | string | `` | AWS secret key |
+| `AWS_S3_BUCKET` | string | `` | S3 bucket name |
+| `AWS_S3_REGION` | string | `us-east-1` | S3 region |
+| `AWS_S3_PREFIX` | string | UUID | S3 key prefix |
+| `EMAIL_USER` | string | `` | SMTP username |
+| `EMAIL_PASS` | string | `` | SMTP password |
+| `EMAIL_TLS_REJECT_UNAUTHORIZED` | string | `true` | TLS cert validation |
+| `PEXELS_KEY` | string | `` | Pexels API key |
+| `LOG_LEVEL` | string | `info` | Pino log level |
+
+---
+
+## Related Documentation
+
+- [Backend Architecture](../backend-architecture.md) - Overall backend structure
+- [Auth Module](./auth.md) - Authentication using JWT helpers
+- [Middleware Module](./middleware.md) - Request middleware
+- [Routes Module](./routes.md) - Route handlers using wrapAsync
+- [Services Module](./services.md) - Business logic services
+- [DB Config Module](./db-config.md) - Database configuration
diff --git a/backend/docs/testing.md b/backend/docs/testing.md
new file mode 100644
index 0000000..9a13eb8
--- /dev/null
+++ b/backend/docs/testing.md
@@ -0,0 +1,77 @@
+# Backend Testing
+
+## Overview
+
+Backend tests use Node.js 24's built-in test runner and TypeScript test files.
+The suite is split into three layers:
+
+| Layer | Command | Location | Purpose |
+|-------|---------|----------|---------|
+| Unit | `npm run test` | `backend/tests/*.test.ts` | Pure helpers, validators, policy decisions, service contracts, and file/session utilities |
+| Integration | `npm run test:integration` | `backend/tests/integration/*.test.ts` | Cross-module behavior such as DB-backed access policy and Express router factory contracts |
+| E2E | `npm run test:e2e` | `backend/tests/e2e/*.test.ts` | Real HTTP request/response checks against local Express test apps |
+| Full suite | `npm run test:all` | all test folders | Runs unit, integration, and e2e in sequence |
+| Verification | `npm run verify` | static checks plus all test folders | Runs typecheck, lint, ESM boundary checks, and the full test suite |
+
+## Current Coverage
+
+- Request validation and `commonErrorHandler` JSON handling.
+- Publish, file upload/presign, upload chunk, and tour page reorder request
+  validation contracts.
+- File service path validation, structured file error payloads, and local
+  presigned URL fallback behavior.
+- Environment validation for config-only runtime settings, including normalized
+  file-storage provider overrides.
+- Circuit breaker behavior for ignored failures, recorded failures, and open
+  breaker rejection.
+- Auth service password reset, password update rejection rules, and email
+  verification token behavior with real bcrypt and DB writes.
+- Route ID/body ID update contract enforcement.
+- Permission name mapping, own-user route bypass, runtime public read bypass,
+  and `AccessPolicy` public-user hardening.
+- Generic DB API and entity service object-signature contracts.
+- OpenAPI route coverage and internal `$ref` resolution.
+- `UploadSessionManager` metadata, chunk tracking, assembly order, and cleanup behavior.
+- `createEntityRouter` service/DB option propagation, query normalization, update ID mismatch handling, and CSV export behavior.
+- Public runtime list blocking and response sanitization for presentation data.
+- Publish service environment copy behavior for dev to stage and stage to production,
+  including target replacement, source preservation, audio tracks, transition
+  settings, and UI-control settings.
+- Runtime context HTTP behavior for default, valid, and unsupported runtime headers.
+
+## Environment Notes
+
+DB-backed integration tests authenticate against the configured PostgreSQL
+connection. If PostgreSQL is unavailable, those tests call `t.skip()` with the
+connection error so non-DB integration tests can still run.
+`npm run test:integration` runs with `--test-concurrency=1` because several
+integration tests share a PostgreSQL transaction connection; keep DB-backed
+tests sequential unless they use isolated connections.
+
+E2E tests bind a local HTTP listener on `127.0.0.1` with an ephemeral port. In
+restricted sandboxes this may require elevated permission for local socket
+binding.
+
+## Test Helpers
+
+`backend/tests/http-test-utils.ts` provides `startTestServer(app)`, which starts
+an Express app on an ephemeral local port and returns `{ baseUrl, close }`.
+Use it only for e2e-style tests that must exercise real HTTP semantics.
+
+Integration tests that do not need a network socket should drive Express apps in
+memory with `node-mocks-http`; this keeps them usable in restricted sandboxes.
+
+## Adding Tests
+
+- Prefer unit tests for pure helpers, validators, policies, and isolated service
+  logic.
+- Use integration tests when behavior crosses route, middleware, service, DB API,
+  or Sequelize transaction boundaries.
+- Use e2e tests when the behavior depends on real HTTP parsing, headers, status
+  codes, or socket-level request handling.
+- Keep new backend tests strict TypeScript compatible and avoid casts, `any`,
+  `eslint-disable`, and `@ts-ignore`.
+- When config-backed behavior must be overridden in tests, mutate the typed
+  config object and restore it in `finally`; do not rely on changing
+  `process.env` after modules have imported `backend/src/config.ts`.
+- For DB integration tests, wrap writes in a transaction and roll it back.
diff --git a/documentation/access-logs-audit-trail.md b/documentation/access-logs-audit-trail.md
new file mode 100644
index 0000000..2d23efd
--- /dev/null
+++ b/documentation/access-logs-audit-trail.md
@@ -0,0 +1,708 @@
+# Access Logs & Audit Trail
+
+Complete documentation for the Tour Builder Platform's Access Logs and Audit Trail system including activity tracking, security auditing, and data preservation.
+
+## Overview
+
+The platform implements a comprehensive audit system with two complementary mechanisms:
+- **Access Logs** - Dedicated table recording API requests with user, path, and client info
+- **Audit Trail** - CreatedBy/UpdatedBy fields on all entities tracking who modified what
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    Access Logs & Audit Trail Architecture                    │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                        Request Flow                                     │ │
+│  │                                                                         │ │
+│  │   Client Request                                                        │ │
+│  │        │                                                                │ │
+│  │        ▼                                                                │ │
+│  │   ┌─────────────────────────────────────────────────────────────────┐  │ │
+│  │   │                    Request Logger Middleware                     │  │ │
+│  │   │                                                                  │  │ │
+│  │   │   • Generate/Extract X-Request-Id                               │  │ │
+│  │   │   • Capture: method, path, user-agent, duration                 │  │ │
+│  │   │   • Log to Pino (structured logging)                            │  │ │
+│  │   └──────────────────────────┬──────────────────────────────────────┘  │ │
+│  │                              │                                          │ │
+│  │                              ▼                                          │ │
+│  │   ┌─────────────────────────────────────────────────────────────────┐  │ │
+│  │   │                    JWT Authentication                            │  │ │
+│  │   │                                                                  │  │ │
+│  │   │   • Validate token                                              │  │ │
+│  │   │   • Attach currentUser to request                               │  │ │
+│  │   └──────────────────────────┬──────────────────────────────────────┘  │ │
+│  │                              │                                          │ │
+│  │                              ▼                                          │ │
+│  │   ┌─────────────────────────────────────────────────────────────────┐  │ │
+│  │   │                    Permission Check                              │  │ │
+│  │   │                                                                  │  │ │
+│  │   │   • Check READ/CREATE/UPDATE/DELETE permissions                 │  │ │
+│  │   │   • Role-based + custom permissions                             │  │ │
+│  │   └──────────────────────────┬──────────────────────────────────────┘  │ │
+│  │                              │                                          │ │
+│  │                              ▼                                          │ │
+│  │   ┌─────────────────────────────────────────────────────────────────┐  │ │
+│  │   │                    Database Operation                            │  │ │
+│  │   │                                                                  │  │ │
+│  │   │   CREATE: set createdById, updatedById                          │  │ │
+│  │   │   UPDATE: set updatedById                                       │  │ │
+│  │   │   DELETE: set deletedBy, mark deletedAt (soft delete)           │  │ │
+│  │   └─────────────────────────────────────────────────────────────────┘  │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Data Model
+
+### Access Logs Schema
+
+**Table:** `access_logs`
+
+**Source:** `backend/src/db/models/access_logs.js`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| id | UUID | Yes | UUIDv4 | Primary key |
+| projectId | UUID (FK) | No | null | Related project (CASCADE delete) |
+| userId | UUID (FK) | No | null | User who accessed (SET NULL delete) |
+| environment | ENUM | Yes | - | 'admin', 'stage', 'production' |
+| path | TEXT | No | null | API path accessed (max 2048 chars) |
+| ip_address | TEXT | No | null | Client IP address (max 45 chars for IPv6) |
+| user_agent | TEXT | No | null | HTTP User-Agent header (max 1024 chars) |
+| accessed_at | TIMESTAMP | Yes | NOW | When access occurred |
+| importHash | VARCHAR(255) | No | null | Unique hash for CSV imports |
+| createdAt | TIMESTAMP | Yes | Auto | Record creation time |
+| updatedAt | TIMESTAMP | Yes | Auto | Record update time |
+| deletedAt | TIMESTAMP | No | null | Soft delete timestamp |
+
+### Indexes
+
+```javascript
+indexes: [
+  { fields: ['projectId'] },     // Query logs by project
+  { fields: ['environment'] },   // Filter by environment
+  { fields: ['userId'] },        // Query logs by user
+  { fields: ['accessed_at'] },   // Time-range queries and sorting
+]
+```
+
+### Relationships
+
+```
+access_logs
+├── belongsTo projects (as project)
+│   ├── foreignKey: projectId
+│   ├── onDelete: CASCADE        ← Logs deleted when project deleted
+│   └── onUpdate: CASCADE
+│
+├── belongsTo users (as user)
+│   ├── foreignKey: userId
+│   ├── onDelete: CASCADE        ← Logs deleted when user deleted
+│   └── onUpdate: CASCADE
+│
+├── belongsTo users (as createdBy) ─── Audit: who created this log
+└── belongsTo users (as updatedBy) ─── Audit: who last updated this log
+```
+
+## Audit Trail Pattern
+
+### CreatedBy/UpdatedBy Implementation
+
+All entities in the system implement the audit trail pattern:
+
+**Source:** `backend/src/db/api/base.api.js`
+
+```javascript
+// On CREATE
+static async create({ data, currentUser = { id: null }, transaction }) {
+  const mappedData = this.getFieldMapping(data);
+
+  const record = await this.MODEL.create({
+    ...mappedData,
+    createdById: currentUser.id,  // Track creator
+    updatedById: currentUser.id,  // Initial updater = creator
+  }, { transaction });
+}
+
+// On UPDATE
+static async update({ id, data, currentUser = { id: null }, transaction }) {
+
+  await record.update({
+    ...updatePayload,
+    updatedById: currentUser.id,  // Track who modified
+  }, { transaction });
+}
+
+// On DELETE (soft delete)
+static async remove({ id, currentUser = { id: null }, transaction }) {
+
+  await record.update({ deletedBy: currentUser.id }, { transaction });
+  await record.destroy({ transaction });  // Sets deletedAt
+}
+```
+
+### Entities with Audit Trail
+
+All models include audit relationships:
+
+```javascript
+// Applied to ALL models:
+db.[entity].belongsTo(db.users, { as: 'createdBy' });
+db.[entity].belongsTo(db.users, { as: 'updatedBy' });
+```
+
+**Audited Entities:**
+- users, roles, permissions
+- projects, project_memberships
+- tour_pages, project_audio_tracks
+- assets, asset_variants
+- element_type_defaults, project_element_defaults
+- publish_events, pwa_caches
+- presigned_url_requests, access_logs
+
+**Note:** Page elements, navigation links, and transitions are stored in `tour_pages.ui_schema_json` and audited as part of the tour_pages record.
+
+### Timestamp Tracking
+
+Sequelize provides automatic timestamps:
+
+```javascript
+{
+  timestamps: true,   // Enables createdAt, updatedAt
+  paranoid: true,     // Enables deletedAt (soft delete)
+}
+```
+
+| Field | Set When | Never Changes |
+|-------|----------|---------------|
+| `createdAt` | Record created | ✓ Immutable |
+| `updatedAt` | Any modification | Updates each save |
+| `deletedAt` | Soft delete called | - |
+
+## Request Logging Middleware
+
+### Logger Configuration
+
+**Source:** `backend/src/utils/logger.js`
+
+```javascript
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport: isDevelopment
+    ? { target: 'pino-pretty', options: { colorize: true } }
+    : undefined,
+  base: {
+    service: 'tour-builder-api',
+    env: process.env.NODE_ENV || 'development',
+  },
+});
+```
+
+### Request Logger Middleware
+
+```javascript
+function requestLogger(req, res, next) {
+  // Generate or extract request ID for tracing
+  const requestId = req.headers['x-request-id'] || crypto.randomUUID();
+  req.log = logger.child({ requestId });
+  req.requestId = requestId;
+  res.setHeader('X-Request-Id', requestId);
+
+  const start = Date.now();
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    const logData = {
+      method: req.method,
+      url: req.originalUrl || req.url,
+      status: res.statusCode,
+      duration,
+      userAgent: req.headers['user-agent'],
+    };
+
+    // Log level based on response status
+    if (res.statusCode >= 500) {
+      req.log.error(logData, 'Request completed with server error');
+    } else if (res.statusCode >= 400) {
+      req.log.warn(logData, 'Request completed with client error');
+    } else {
+      req.log.info(logData, 'Request completed');
+    }
+  });
+
+  next();
+}
+```
+
+### Applied in Application
+
+**Source:** `backend/src/index.ts`
+
+```javascript
+app.enable('trust proxy');  // Extract real IP behind proxies
+app.use(requestLogger);     // Apply to all routes
+```
+
+### Log Output Format
+
+**Development (pino-pretty):**
+```
+[10:30:45.123] INFO: Request completed
+    method: "GET"
+    url: "/api/projects"
+    status: 200
+    duration: 45
+    userAgent: "Mozilla/5.0..."
+    requestId: "abc123-def456"
+```
+
+**Production (JSON):**
+```json
+{
+  "level": 30,
+  "time": 1711234567890,
+  "service": "tour-builder-api",
+  "env": "production",
+  "requestId": "abc123-def456",
+  "method": "GET",
+  "url": "/api/projects",
+  "status": 200,
+  "duration": 45,
+  "userAgent": "Mozilla/5.0..."
+}
+```
+
+## API Reference
+
+### Endpoints
+
+**Source:** `backend/src/routes/access_logs.ts`
+
+| Method | Endpoint | Permission | Description |
+|--------|----------|------------|-------------|
+| GET | `/api/access_logs` | READ_ACCESS_LOGS | List with filtering |
+| GET | `/api/access_logs/:id` | READ_ACCESS_LOGS | Get single log |
+| POST | `/api/access_logs` | CREATE_ACCESS_LOGS | Create log entry |
+| PUT | `/api/access_logs/:id` | UPDATE_ACCESS_LOGS | Update log |
+| DELETE | `/api/access_logs/:id` | DELETE_ACCESS_LOGS | Soft delete log |
+
+### Query Parameters
+
+**Source:** `backend/src/db/api/access_logs.ts`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `limit` | number | Results per page (default: 50) |
+| `page` | number | Page number (0-based) |
+| `field` | string | Sort field |
+| `sort` | 'asc' \| 'desc' | Sort direction |
+| `path` | string | Search path (ILIKE) |
+| `ip_address` | string | Search IP address (ILIKE) |
+| `user_agent` | string | Search user agent (ILIKE) |
+| `accessed_atRange` | [start, end] | Date range filter |
+| `environment` | enum | Filter by environment |
+| `project` | UUID \| string | Filter by project |
+| `user` | UUID \| string | Filter by user |
+| `filetype` | 'csv' | Export as CSV |
+
+### Request/Response Examples
+
+**List Logs with Filters:**
+```http
+GET /api/access_logs?limit=50&page=1&environment=production&accessed_atRange=["2024-01-01","2024-12-31"]&sort=DESC&field=accessed_at
+Authorization: Bearer <jwt-token>
+```
+
+**Response:**
+```json
+{
+  "rows": [
+    {
+      "id": "log-uuid-1",
+      "projectId": "project-uuid",
+      "userId": "user-uuid",
+      "environment": "production",
+      "path": "/api/tour_pages",
+      "ip_address": "192.168.1.100",
+      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
+      "accessed_at": "2024-03-15T10:30:00Z",
+      "project": {
+        "id": "project-uuid",
+        "name": "My Tour"
+      },
+      "user": {
+        "id": "user-uuid",
+        "firstName": "John",
+        "lastName": "Doe"
+      },
+      "createdAt": "2024-03-15T10:30:00Z",
+      "updatedAt": "2024-03-15T10:30:00Z"
+    }
+  ],
+  "count": 1542
+}
+```
+
+**Create Log Entry:**
+```http
+POST /api/access_logs
+Content-Type: application/json
+Authorization: Bearer <jwt-token>
+
+{
+  "data": {
+    "project": "project-uuid",
+    "user": "user-uuid",
+    "environment": "production",
+    "path": "/api/tour_pages",
+    "ip_address": "192.168.1.100",
+    "user_agent": "Mozilla/5.0...",
+    "accessed_at": "2024-03-15T10:30:00Z"
+  }
+}
+```
+
+### CSV Export
+
+**Fields Exported:**
+- id
+- environment
+- path
+- ip_address
+- user_agent
+- accessed_at
+- createdAt
+
+```http
+GET /api/access_logs?filetype=csv
+Authorization: Bearer <jwt-token>
+```
+
+## Frontend Implementation
+
+### Admin Pages
+
+**Location:** `frontend/src/pages/access_logs/`
+
+| Page | Path | Description |
+|------|------|-------------|
+| List | `/access_logs/access_logs-list` | Filterable table view |
+| Table | `/access_logs/access_logs-table` | Data grid variant |
+| New | `/access_logs/access_logs-new` | Create log entry |
+| Edit | `/access_logs/access_logs-edit?id=<uuid>` | Edit log |
+| View | `/access_logs/access_logs-view?id=<uuid>` | Read-only details |
+| Dynamic | `/access_logs/[access_logsId]` | Dynamic route (ID in path) |
+
+**Note:** Uses `useEditPageSync` hook for edit page data synchronization.
+
+### List Page Filters
+
+**Source:** `frontend/src/pages/access_logs/access_logs-list.tsx`
+
+| Filter | Type | Description |
+|--------|------|-------------|
+| Path | Text | Search by API path |
+| IP Address | Text | Search by client IP |
+| User Agent | Text | Search by browser/client |
+| Accessed At | Date Range | Filter by time range |
+| Project | Dropdown | Filter by project |
+| User | Dropdown | Filter by user |
+| Environment | Enum | admin / stage / production |
+
+### Table Columns
+
+**Source:** `frontend/src/components/Access_logs/configureAccess_logsCols.tsx`
+
+Uses `createColumnLoader` factory from `configBuilderFactory.tsx`:
+
+| Column | Editable | Type |
+|--------|----------|------|
+| project | Yes | singleSelectRelation (projects) |
+| environment | Yes | text |
+| user | Yes | singleSelectRelation (users) |
+| path | Yes | text |
+| ip_address | Yes | text |
+| user_agent | Yes | text |
+| accessed_at | Yes | datetime |
+| actions | - | actions (Edit / View / Delete) |
+
+### TypeScript Interface
+
+**Source:** `frontend/src/types/entities.ts`
+
+```typescript
+export interface AccessLog extends BaseEntity {
+  user?: User | string | null;
+  project?: Project | string | null;
+  environment?: 'admin' | 'stage' | 'production';
+  path?: string;
+  action?: string;
+  ip_address?: string;
+  user_agent?: string;
+  accessed_at?: string | Date;
+  metadata?: Record<string, unknown>;
+}
+```
+
+### Redux State
+
+**Source:** `frontend/src/stores/access_logs/access_logsSlice.ts`
+
+Uses `createEntitySlice` factory for standardized CRUD operations:
+
+```typescript
+const { slice, actions, reducer } = createEntitySlice<AccessLog>({
+  name: 'access_logs',
+  endpoint: 'access_logs',
+  singularName: 'Access Log',
+});
+
+export const {
+  fetch,           // Load logs with query
+  create,          // Create new log
+  update,          // Update existing log
+  deleteItem,      // Delete single log
+  deleteItemsByIds,// Batch delete
+  uploadCsv,       // Import from CSV
+  setRefetch,      // Trigger refresh
+} = actions;
+
+// Usage
+dispatch(fetch({ query: '?environment=production&limit=100' }));
+```
+
+## Security & Permissions
+
+### Role-Permission Matrix
+
+**Source:** `backend/src/db/seeders/20200430130760-user-roles.js`
+
+| Role | CREATE | READ | UPDATE | DELETE |
+|------|--------|------|--------|--------|
+| PlatformOwner | ✓ | ✓ | ✓ | ✓ |
+| Administrator | ✓ | ✓ | ✓ | ✓ |
+| AccountManager | ✗ | ✓ | ✗ | ✗ |
+| TourDesigner | ✗ | ✓ | ✗ | ✗ |
+| ContentReviewer | ✗ | ✓ | ✗ | ✗ |
+| AnalyticsViewer | ✗ | ✓ | ✗ | ✗ |
+
+### Permission Check Flow
+
+```
+Request → JWT Auth → checkCrudPermissions('access_logs') → Route Handler
+                              │
+                              ▼
+              ┌───────────────────────────────┐
+              │  1. AccessPolicy              │
+              │  2. Custom user permissions   │
+              │  3. Role-based permissions    │
+              │  4. Public hardening          │
+              └───────────────────────────────┘
+```
+
+### Cascade Delete Behavior
+
+Both user and project deletions cascade to access logs:
+
+```javascript
+// access_logs -> users
+onDelete: 'CASCADE'   // Logs deleted with user
+
+// access_logs -> projects
+onDelete: 'CASCADE'   // Logs deleted with project
+```
+
+> **Note:** Access logs are NOT preserved when users or projects are deleted. If audit history retention is required, consider archiving logs before deletion or implementing SET NULL behavior.
+
+## Data Capture Scope
+
+### What IS Captured
+
+| Data Point | Location | Purpose |
+|------------|----------|---------|
+| User ID | access_logs.userId | Who made the request |
+| Project ID | access_logs.projectId | Which project context |
+| API Path | access_logs.path | What endpoint accessed |
+| IP Address | access_logs.ip_address | Client location/identity |
+| User Agent | access_logs.user_agent | Browser/client identification |
+| Timestamp | access_logs.accessed_at | When it happened |
+| Environment | access_logs.environment | admin/stage/production |
+
+### What IS NOT Captured
+
+| Data Point | Reason |
+|------------|--------|
+| Request body | Privacy protection |
+| Response content | Privacy/performance |
+| Query parameters | Only path stored |
+| Authentication credentials | Security |
+| Personal user data | Beyond ID reference |
+
+### Audit Trail vs Access Logs
+
+| Aspect | Audit Trail | Access Logs |
+|--------|-------------|-------------|
+| Scope | All entities | Dedicated table |
+| Granularity | Per-record changes | Per-request |
+| Data | Who modified when | Request details |
+| Retention | With entity | Separate lifecycle |
+| Purpose | Change tracking | Security monitoring |
+
+## Soft Delete & Retention
+
+### Paranoid Mode
+
+```javascript
+{
+  timestamps: true,
+  paranoid: true,  // Enables soft deletes
+}
+```
+
+### Deletion Behavior
+
+1. **Soft Delete**: Sets `deletedAt` timestamp
+2. **Query Filtering**: Normal queries exclude deleted records
+3. **Restoration**: Possible by clearing `deletedAt`
+4. **Hard Delete**: Requires explicit permanent removal
+
+### Retention Considerations
+
+**Current Implementation:**
+- No automatic log pruning
+- Logs retained indefinitely
+- Manual cleanup via DELETE endpoints
+
+**Recommended Practices:**
+- Implement TTL-based cleanup for old logs
+- Archive logs to cold storage after 90 days
+- Consider GDPR right-to-erasure requirements
+
+## File Structure
+
+### Backend
+
+| File | Purpose |
+|------|---------|
+| `backend/src/db/models/access_logs.js` | Sequelize model definition |
+| `backend/src/db/api/access_logs.ts` | Database API (CRUD) |
+| `backend/src/db/api/base.api.js` | Audit trail implementation |
+| `backend/src/routes/access_logs.ts` | REST endpoints |
+| `backend/src/services/access_logs.ts` | Business logic |
+| `backend/src/utils/logger.js` | Request logging middleware |
+| `backend/src/middlewares/check-permissions.ts` | Permission enforcement |
+
+### Frontend
+
+| File | Purpose |
+|------|---------|
+| `frontend/src/pages/access_logs/access_logs-list.tsx` | List page |
+| `frontend/src/pages/access_logs/access_logs-table.tsx` | Table page |
+| `frontend/src/pages/access_logs/access_logs-new.tsx` | Create page |
+| `frontend/src/pages/access_logs/access_logs-edit.tsx` | Edit page |
+| `frontend/src/pages/access_logs/access_logs-view.tsx` | View page |
+| `frontend/src/pages/access_logs/[access_logsId].tsx` | Dynamic route |
+| `frontend/src/stores/access_logs/access_logsSlice.ts` | Redux state (createEntitySlice) |
+| `frontend/src/components/Access_logs/TableAccess_logs.tsx` | Data grid component |
+| `frontend/src/components/Access_logs/ListAccess_logs.tsx` | List view component |
+| `frontend/src/components/Access_logs/CardAccess_logs.tsx` | Card view component |
+| `frontend/src/components/Access_logs/configureAccess_logsCols.tsx` | Column config (createColumnLoader) |
+| `frontend/src/types/entities.ts` | TypeScript interfaces |
+
+## Known Considerations
+
+### 1. Manual Log Creation
+
+**Issue:** Access logs are typically created manually via API, not automatically by middleware.
+
+**Impact:** Requires explicit logging calls or additional middleware to auto-populate.
+
+### 2. User Deletion Cascades
+
+**Issue:** `CASCADE` on userId means logs are deleted when user is deleted.
+
+**Impact:** Audit history lost with user deletion. Consider archiving logs before user deletion or changing to `SET NULL` for preservation.
+
+### 3. Project Deletion Cascades
+
+**Issue:** All access logs deleted when project is deleted.
+
+**Impact:** Audit history lost with project. Consider archiving before deletion.
+
+### 4. No Query Parameter Logging
+
+**Issue:** Only `path` is stored, not query strings.
+
+**Impact:** Cannot reconstruct full request URL. May miss filter/search context.
+
+### 5. IPv6 Support
+
+**Issue:** `ip_address` limited to 45 characters.
+
+**Impact:** Supports full IPv6 addresses (39 chars max). Adequate for current needs.
+
+### 6. User Agent Truncation
+
+**Issue:** `user_agent` limited to 1024 characters.
+
+**Impact:** Very long user agents may be truncated. Rare but possible.
+
+### 7. No Automatic Retention
+
+**Issue:** Logs grow indefinitely without cleanup.
+
+**Impact:** Database size increases over time. Recommend implementing retention policy.
+
+### 8. TypeScript Interface Extras
+
+**Issue:** Frontend `AccessLog` interface includes `action` and `metadata` fields not in database model.
+
+**Impact:** These fields exist only in TypeScript for potential future use. Currently not persisted.
+
+## Integration Examples
+
+### Log Access in Custom Middleware
+
+```javascript
+import Access_logsDBApi from '../db/api/access_logs.ts';
+
+async function logAccess(req, res, next) {
+  // Log after response completes
+  res.on('finish', async () => {
+    try {
+      await Access_logsDBApi.create({
+        project: req.project?.id,
+        user: req.currentUser?.id,
+        environment: determineEnvironment(req),
+        path: req.path,
+        ip_address: req.ip,
+        user_agent: req.headers['user-agent'],
+        accessed_at: new Date(),
+      }, { currentUser: req.currentUser });
+    } catch (err) {
+      // Don't fail request on logging error
+      console.error('Failed to log access:', err);
+    }
+  });
+  next();
+}
+```
+
+### Query Logs by Time Range
+
+```typescript
+// Frontend
+dispatch(fetch({
+  query: '?accessed_atRange=["2024-01-01T00:00:00Z","2024-01-31T23:59:59Z"]&environment=production&sort=DESC&field=accessed_at'
+}));
+```
+
+### Export Logs for Compliance
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://api.example.com/api/access_logs?filetype=csv&accessed_atRange=[\"2024-01-01\",\"2024-03-31\"]" \
+  > access_logs_q1_2024.csv
+```
diff --git a/documentation/api-reference.md b/documentation/api-reference.md
new file mode 100644
index 0000000..8c03521
--- /dev/null
+++ b/documentation/api-reference.md
@@ -0,0 +1,1700 @@
+# API Reference - E2E Documentation
+
+## Overview
+
+The Tour Builder Platform exposes a RESTful API built with Express.js. All endpoints follow consistent patterns for CRUD operations, authentication, and response formats.
+
+**Base URL:** `http://localhost:3000/api` for local development.
+
+**Standard VM:** Apache serves the public domain on port `80`, the frontend
+PM2 app listens on `3001`, and the backend PM2 app listens on `3000` with
+`NODE_ENV=dev_stage`. Use `http://127.0.0.1:3000/api/...` for direct VM backend
+checks, or `http://tbp.flatlogic.app/api/...` through Apache/Cloudflare. See
+[deployment-vm.md](deployment-vm.md).
+
+---
+
+## Authentication
+
+### JWT Bearer Token
+
+Most endpoints require JWT authentication via the Authorization header:
+
+```
+Authorization: Bearer <token>
+```
+
+**Token Details:**
+- Expiration: 6 hours
+- Payload: `{ id, email, name }`
+- Obtained via `/api/auth/signin/local` or OAuth callbacks
+
+### Public Endpoints (No Auth Required)
+
+- `GET /api/health`
+- `POST /api/auth/signin/local`
+- `POST /api/auth/send-password-reset-email`
+- `PUT /api/auth/password-reset`
+- `PUT /api/auth/verify-email`
+- `GET /api/auth/email-configured`
+- `GET /api/auth/signin/google`
+- `GET /api/auth/signin/microsoft`
+- `GET /api/runtime-context`
+
+### Runtime Public Access
+
+In **production** runtime mode only, certain GET endpoints allow unauthenticated read access (stage requires authentication):
+- `GET /api/projects`
+- `GET /api/tour_pages`
+- `GET /api/project_audio_tracks`
+- `GET /api/global-ui-control-defaults`
+- `GET /api/project-ui-control-settings/project/:projectId/env/production`
+
+**Note:** The `X-Runtime-Environment` header must be set to `production` for public access. Stage environment (`stage`) requires JWT authentication as it serves as a workspace for review.
+
+---
+
+## Standard Response Formats
+
+### Success Responses
+
+**Single Entity:**
+```json
+{
+  "id": "uuid-here",
+  "name": "Entity Name",
+  "createdAt": "2024-01-01T00:00:00.000Z",
+  "updatedAt": "2024-01-01T00:00:00.000Z"
+}
+```
+
+**List Response:**
+```json
+{
+  "rows": [
+    { "id": "uuid-1", "name": "Entity 1" },
+    { "id": "uuid-2", "name": "Entity 2" }
+  ],
+  "count": 100
+}
+```
+
+**Count Response:**
+```json
+{
+  "count": 100
+}
+```
+
+### Error Responses
+
+```json
+{
+  "error": "Error message description"
+}
+```
+
+**HTTP Status Codes:**
+| Code | Description |
+|------|-------------|
+| 200 | Success |
+| 201 | Created |
+| 400 | Bad Request (validation errors) |
+| 401 | Unauthorized (missing/invalid token) |
+| 403 | Forbidden (insufficient permissions) |
+| 404 | Not Found |
+| 429 | Too Many Requests (rate limited) |
+| 500 | Internal Server Error |
+
+---
+
+## Rate Limiting
+
+The API uses rate limiting to prevent abuse. Rate limits are applied per IP address, and rate limit headers are returned with each response:
+
+| Header | Description |
+|--------|-------------|
+| `X-RateLimit-Limit` | Maximum requests allowed per window |
+| `X-RateLimit-Remaining` | Remaining requests in current window |
+| `X-RateLimit-Reset` | ISO timestamp when the window resets |
+| `Retry-After` | Seconds until you can retry (when limited) |
+
+### Rate Limit Configuration
+
+| Limiter | Window | Max Requests | Endpoints |
+|---------|--------|--------------|-----------|
+| **Auth** | 15 minutes | 10 | `/api/auth/signin/*` |
+| **Password Reset** | 1 hour | 5 | `/api/auth/send-password-reset-email` |
+| **API** | 1 minute | 100 | General API endpoints |
+| **Upload** | 1 minute | 10 | `/api/file/upload*` |
+| **Download** | 1 minute | 200 | `/api/file/download`, `/api/file/presign` |
+| **Search** | 1 minute | 30 | `/api/search` |
+
+**Note:** Rate limiting is skipped for localhost (`127.0.0.1`, `::1`) in development mode.
+
+---
+
+## Standard Entity Endpoints
+
+All entity routes (projects, assets, users, etc.) support these standard endpoints:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/{entity}` | List entities (paginated) |
+| `GET` | `/api/{entity}/count` | Get count only |
+| `GET` | `/api/{entity}/autocomplete` | Autocomplete search |
+| `GET` | `/api/{entity}/:id` | Get single entity by ID |
+| `POST` | `/api/{entity}` | Create entity |
+| `PUT` | `/api/{entity}/:id` | Update entity |
+| `DELETE` | `/api/{entity}/:id` | Delete entity |
+| `POST` | `/api/{entity}/deleteByIds` | Bulk delete |
+| `POST` | `/api/{entity}/bulk-import` | CSV import |
+
+### GET /api/{entity}/count
+
+Get count of entities matching the query.
+
+**Query Parameters:** Same as list endpoint
+
+**Response:**
+```json
+{
+  "count": 100
+}
+```
+
+### GET /api/{entity}/autocomplete
+
+Get autocomplete suggestions for a field.
+
+**Query Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Search query |
+| `limit` | number | Max results (default: 10) |
+| `offset` | number | Pagination offset |
+
+**Response:**
+```json
+[
+  { "id": "uuid-1", "label": "Option 1" },
+  { "id": "uuid-2", "label": "Option 2" }
+]
+```
+
+---
+
+## Standard Query Parameters
+
+All list endpoints support these query parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `limit` | number | 10 | Items per page |
+| `offset` | number | 0 | Pagination offset |
+| `page` | number | 0 | Page number (alternative to offset) |
+| `search` | string | - | Text search across searchable fields |
+| `sort` | string | - | Sort field (e.g., `name` or `name:DESC`) |
+| `filetype` | string | - | Export format (`csv`) |
+
+### Entity-Specific Filters
+
+Filters vary by entity based on their `SEARCHABLE_FIELDS`, `RANGE_FIELDS`, and `ENUM_FIELDS`:
+
+```
+# Text search
+?search=keyword
+
+# Range filters (numeric/date)
+?createdAtRange=2024-01-01,2024-12-31
+?sizeRange=0,1000000
+
+# Enum/exact match filters
+?type=image
+?status=active
+?environment=production
+
+# Relationship filters
+?projectId=uuid
+?tour_pageId=uuid
+```
+
+---
+
+## Authentication Endpoints
+
+### POST /api/auth/signin/local
+
+Login with email and password.
+
+**Rate Limit:** 10 requests per 15 minutes
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "user-uuid",
+  "email": "user@example.com",
+  "firstName": "John",
+  "lastName": "Doe",
+  "token": "eyJhbGciOiJIUzI1NiIs..."
+}
+```
+
+### Self-Registration
+
+Self-registration is disabled. The API does not expose
+`POST /api/auth/signup`; new users are created through the authenticated Users
+flow and receive an invitation/setup link.
+
+### GET /api/auth/me
+
+Get current authenticated user.
+
+**Auth:** Required
+
+**Response:**
+```json
+{
+  "id": "user-uuid",
+  "email": "user@example.com",
+  "firstName": "John",
+  "lastName": "Doe",
+  "app_role": {
+    "id": "role-uuid",
+    "name": "Admin"
+  }
+}
+```
+
+### PUT /api/auth/password-update
+
+Update password for authenticated user.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "currentPassword": "oldpassword",
+  "newPassword": "newpassword123"
+}
+```
+
+### POST /api/auth/send-password-reset-email
+
+Send password reset email.
+
+**Rate Limit:** 5 requests per hour
+
+**Request:**
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+### POST /api/auth/send-email-address-verification-email
+
+Resend email verification email for current user.
+
+**Auth:** Required
+
+**Response:** `true` on success
+
+### PUT /api/auth/password-reset
+
+Reset password with token.
+
+**Request:**
+```json
+{
+  "token": "reset-token-from-email",
+  "password": "newpassword123"
+}
+```
+
+### PUT /api/auth/profile
+
+Update user profile.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "profile": {
+    "firstName": "John",
+    "lastName": "Doe",
+    "phoneNumber": "+1234567890"
+  }
+}
+```
+
+### OAuth Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/auth/signin/google` | Initiate Google OAuth |
+| `GET /api/auth/signin/google/callback` | Google OAuth callback |
+| `GET /api/auth/signin/microsoft` | Initiate Microsoft OAuth |
+| `GET /api/auth/signin/microsoft/callback` | Microsoft OAuth callback |
+
+---
+
+## System Endpoints
+
+### GET /api/health
+
+Health check endpoint.
+
+**Auth:** Not required
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "uptime": 3600,
+  "environment": "production",
+  "database": "connected"
+}
+```
+
+### GET /api/runtime-context
+
+Get runtime context information.
+
+**Auth:** Not required
+
+**Response:**
+```json
+{
+  "mode": "admin",
+  "projectSlug": null
+}
+```
+
+**Modes:**
+- `admin` - Full access (localhost or admin subdomain)
+- `stage` - Stage environment (stage.{project}.domain)
+- `production` - Production environment ({project}.domain)
+
+---
+
+## File Endpoints
+
+### POST /api/file/upload-sessions/init
+
+Initialize chunked upload session.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "filename": "video.mp4",
+  "size": 104857600,
+  "mimeType": "video/mp4",
+  "projectId": "project-uuid"
+}
+```
+
+**Response:**
+```json
+{
+  "sessionId": "session-uuid",
+  "chunkSize": 5242880,
+  "totalChunks": 20,
+  "expiresAt": "2024-01-02T00:00:00.000Z"
+}
+```
+
+### GET /api/file/upload-sessions/:sessionId
+
+Get upload session status.
+
+**Auth:** Required
+
+**Response:**
+```json
+{
+  "sessionId": "session-uuid",
+  "filename": "video.mp4",
+  "uploadedChunks": [0, 1, 2],
+  "totalChunks": 20,
+  "status": "uploading"
+}
+```
+
+### PUT /api/file/upload-sessions/:sessionId/chunks/:chunkIndex
+
+Upload file chunk.
+
+**Auth:** Required
+
+**Content-Type:** `application/octet-stream`
+
+**Body:** Raw binary data
+
+**Response:**
+```json
+{
+  "chunkIndex": 0,
+  "received": true
+}
+```
+
+### POST /api/file/upload-sessions/:sessionId/finalize
+
+Finalize chunked upload.
+
+**Auth:** Required
+
+**Response:**
+```json
+{
+  "success": true,
+  "asset": {
+    "id": "asset-uuid",
+    "url": "https://cdn.example.com/video.mp4",
+    "storageKey": "uploads/video.mp4"
+  }
+}
+```
+
+### GET /api/file/download
+
+Download file.
+
+**Query Parameters:**
+- `privateUrl` - Encoded file path
+- `id` - Asset ID (alternative)
+
+**Response:** File stream with appropriate Content-Type
+
+### POST /api/file/presign
+
+Generate presigned URLs for batch asset downloads. For S3 storage, returns direct S3 signed URLs for client-side downloads (bypassing the backend). For other storage providers, returns backend proxy URLs.
+
+**Auth:** Not required (public endpoint for runtime asset preloading)
+
+**Request:**
+```json
+{
+  "urls": [
+    "uploads/projects/abc/image1.jpg",
+    "uploads/projects/abc/video.mp4",
+    "uploads/projects/abc/audio.mp3"
+  ]
+}
+```
+
+**Limits:**
+- Maximum 50 URLs per request
+- All URLs must be non-empty strings
+
+**Response:**
+```json
+{
+  "presignedUrls": {
+    "uploads/projects/abc/image1.jpg": "https://bucket.s3.region.amazonaws.com/uploads/projects/abc/image1.jpg?X-Amz-...",
+    "uploads/projects/abc/video.mp4": "https://bucket.s3.region.amazonaws.com/uploads/projects/abc/video.mp4?X-Amz-...",
+    "uploads/projects/abc/audio.mp3": "https://bucket.s3.region.amazonaws.com/uploads/projects/abc/audio.mp3?X-Amz-..."
+  }
+}
+```
+
+**Presigned URL Expiry:** 1 hour (3600 seconds)
+
+**Use Case:** Frontend preloading uses this endpoint to get direct S3 download URLs, enabling:
+- Parallel asset downloads without backend proxy overhead
+- Direct storage in browser Cache API
+- Blob URL creation for instant display
+
+### POST /api/file/upload/:table/:field
+
+Legacy single-file upload.
+
+**Auth:** Required
+
+**Content-Type:** `multipart/form-data`
+
+---
+
+## Projects Endpoints
+
+### POST /api/projects
+
+Create a new project.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "name": "My Tour",
+    "slug": "my-tour",
+    "description": "A virtual tour",
+    "logo_url": "https://...",
+    "favicon_url": "https://...",
+    "og_image_url": "https://...",
+    "theme_config_json": {},
+    "custom_css_json": {},
+    "cdn_base_url": "https://cdn.example.com"
+  }
+}
+```
+
+### GET /api/projects
+
+List all projects.
+
+**Auth:** Optional (runtime public mode)
+
+**Query Parameters:**
+- Standard pagination/filtering
+
+**Response:**
+```json
+{
+  "rows": [
+    {
+      "id": "project-uuid",
+      "name": "My Tour",
+      "slug": "my-tour",
+      "tour_pages": [...],
+      "assets": [...]
+    }
+  ],
+  "count": 10
+}
+```
+
+### GET /api/projects/:id
+
+Get project by ID.
+
+**Auth:** Optional (runtime public mode)
+
+**Includes:** tour_pages, assets, project_audio_tracks, project_element_defaults
+
+### PUT /api/projects/:id
+
+Update project.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "id": "project-uuid",
+  "data": {
+    "name": "Updated Tour Name"
+  }
+}
+```
+
+### DELETE /api/projects/:id
+
+Delete project.
+
+**Auth:** Required
+
+### POST /api/projects/:id/clone
+
+Clone project with all related entities.
+
+**Auth:** Required
+
+**Response:**
+```json
+{
+  "id": "new-project-uuid",
+  "name": "My Tour (Copy)",
+  "slug": "my-tour-copy"
+}
+```
+
+### POST /api/publish/save-to-stage
+
+Copy all `dev` environment content to `stage` for preview.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "projectId": "project-uuid"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "publishEventId": "event-uuid",
+  "summary": {
+    "pages_copied": 10,
+    "audios_copied": 2
+  }
+}
+```
+
+**Note:** This is part of the dev → stage → production workflow. Content is edited in `dev` (Constructor), previewed in `stage`, then published to `production`. Page elements, navigation, and transitions are stored in `tour_pages.ui_schema_json` and copied with pages.
+
+## Tour Pages Endpoints
+
+### POST /api/tour_pages
+
+Create a tour page.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "title": "Home Page",
+    "slug": "home",
+    "sort_order": 0,
+    "projectId": "project-uuid",
+    "environment": "dev",
+    "background_image_url": "https://...",
+    "background_video_url": "https://...",
+    "ui_schema_json": {}
+  }
+}
+```
+
+### GET /api/tour_pages
+
+List tour pages.
+
+**Auth:** Optional (runtime public mode)
+
+**Query Parameters:**
+- `projectId` - Filter by project
+- `environment` - Filter by environment
+
+### GET /api/tour_pages/:id
+
+Get tour page by ID.
+
+**Includes:** project
+
+**Note:** Page elements are stored directly in the `ui_schema_json` field.
+
+### PUT /api/tour_pages/:id
+
+Update tour page.
+
+**Auth:** Required
+
+### POST /api/tour_pages/reorder
+
+Update page order within a project/environment without touching page content.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "projectId": "project-uuid",
+    "environment": "dev",
+    "orderedPageIds": ["page-uuid-1", "page-uuid-2", "page-uuid-3"]
+  }
+}
+```
+
+**Behavior:**
+- Reordering is allowed only in `dev`.
+- `orderedPageIds` must contain every dev page in that project exactly once.
+- Duplicate IDs, missing IDs, IDs from another project, and unknown IDs are
+  rejected.
+- The backend updates only `sort_order`; page content, slugs, navigation links,
+  and media fields are not changed.
+- Stage receives the new order after `POST /api/publish/save-to-stage`.
+- Production receives the new order after `POST /api/publish`.
+
+**Response:**
+```json
+[
+  { "id": "page-uuid-1", "sort_order": 1 },
+  { "id": "page-uuid-2", "sort_order": 2 },
+  { "id": "page-uuid-3", "sort_order": 3 }
+]
+```
+
+**Errors:**
+| Status | Reason |
+|--------|--------|
+| 400 | Missing `projectId`, invalid `orderedPageIds`, duplicate/missing pages, or `environment` other than `dev` |
+| 403 | Authenticated user is not allowed to update pages in the project |
+
+### POST /api/tour_pages/:id/duplicate
+
+Duplicate a dev tour page into a new independent dev page.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "projectId": "project-uuid",
+    "environment": "dev",
+    "name": "Lobby Copy",
+    "slug": "lobby-copy"
+  }
+}
+```
+
+**Behavior:**
+- Only dev pages can be duplicated. Stage and production are updated through
+  Save to Stage and Publish.
+- The duplicate receives a new page ID, unique slug, blank `source_key`, and
+  `sort_order = max(project dev sort_order) + 1`.
+- Page media/settings fields and `ui_schema_json` are copied from the source
+  page.
+- Inline element IDs and nested item IDs in `ui_schema_json` are regenerated so
+  the new page can be edited independently.
+- Asset URLs, transition URLs, and navigation `targetPageSlug` values are
+  preserved.
+- Existing reverse-video processing still runs through `TourPagesService`, so
+  transition reverse URLs are handled consistently with normal page save/create.
+
+**Response:** Created tour page record.
+
+**Errors:**
+| Status | Reason |
+|--------|--------|
+| 400 | Missing source page, source page outside project, or non-dev source/target environment |
+| 403 | Authenticated user is not allowed to create/update pages in the project |
+
+### DELETE /api/tour_pages/:id
+
+Delete tour page.
+
+**Auth:** Required
+
+**Constructor behavior:** the constructor uses this same endpoint for the active
+dev page after showing a confirmation modal. After deletion it reloads page data
+and selects the next page in presentation order when available.
+
+---
+
+## Assets Endpoints
+
+### POST /api/assets
+
+Create an asset record.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "name": "Hero Image",
+    "cdn_url": "https://cdn.example.com/image.jpg",
+    "storage_key": "uploads/image.jpg",
+    "mime_type": "image/jpeg",
+    "checksum": "abc123...",
+    "width_px": 1920,
+    "height_px": 1080,
+    "size_mb": 0.5,
+    "duration_sec": null,
+    "projectId": "project-uuid"
+  }
+}
+```
+
+### GET /api/assets
+
+List assets.
+
+**Auth:** Required
+
+**Query Parameters:**
+- `projectId` - Filter by project
+- `mime_type` - Filter by MIME type
+
+**Includes:** asset_variants, project
+
+### GET /api/assets/:id
+
+Get asset by ID.
+
+**Includes:** asset_variants
+
+### PUT /api/assets/:id
+
+Update asset.
+
+**Auth:** Required
+
+### DELETE /api/assets/:id
+
+Delete asset (and file from storage).
+
+**Auth:** Required
+
+---
+
+## Asset Variants Endpoints
+
+### POST /api/asset_variants
+
+Create an asset variant.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "assetId": "asset-uuid",
+    "variant_type": "webp",
+    "cdn_url": "https://cdn.example.com/image.webp",
+    "storage_key": "uploads/image.webp",
+    "mime_type": "image/webp",
+    "width_px": 1920,
+    "height_px": 1080,
+    "size_bytes": 51200
+  }
+}
+```
+
+**Variant Types:**
+- `thumbnail` - Small preview
+- `preview` - Medium preview
+- `webp` - WebP format
+- `mp4_low` - Low quality video
+- `mp4_high` - High quality video
+- `original` - Original file
+
+### GET /api/asset_variants
+
+List asset variants.
+
+**Auth:** Required
+
+**Query Parameters:**
+- `assetId` - Filter by parent asset
+- `variant_type` - Filter by variant type
+
+---
+
+## Project Audio Tracks Endpoints
+
+### POST /api/project_audio_tracks
+
+Create a project audio track.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "name": "Background Music",
+    "projectId": "project-uuid",
+    "audio_url": "https://cdn.example.com/music.mp3",
+    "duration_sec": 180,
+    "volume": 0.8,
+    "loop": true,
+    "autoplay": true
+  }
+}
+```
+
+### GET /api/project_audio_tracks
+
+List audio tracks.
+
+**Auth:** Optional (runtime public mode)
+
+**Query Parameters:**
+- `projectId` - Filter by project
+
+---
+
+## Project Memberships Endpoints
+
+Manage team collaboration and per-project access control.
+
+### POST /api/project_memberships
+
+Create a project membership (invite user to project).
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "projectId": "project-uuid",
+    "userId": "user-uuid",
+    "access_level": "editor",
+    "is_active": true,
+    "invited_at": "2024-01-01T00:00:00.000Z"
+  }
+}
+```
+
+**Access Levels:** `owner`, `editor`, `reviewer`, `viewer`
+
+### GET /api/project_memberships
+
+List project memberships.
+
+**Auth:** Required
+
+**Query Parameters:**
+- `projectId` or `project` - Filter by project
+- `userId` or `user` - Filter by user
+- `access_level` - Filter by access level
+- `is_active` - Filter by active status
+
+### GET /api/project_memberships/:id
+
+Get project membership by ID.
+
+**Auth:** Required
+
+**Includes:** project, user
+
+### PUT /api/project_memberships/:id
+
+Update project membership.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "id": "membership-uuid",
+  "data": {
+    "access_level": "viewer",
+    "is_active": false
+  }
+}
+```
+
+### DELETE /api/project_memberships/:id
+
+Remove user from project.
+
+**Auth:** Required
+
+---
+
+## PWA Caches Endpoints
+
+Track PWA cache versions and offline asset manifests per project.
+
+### POST /api/pwa_caches
+
+Create a PWA cache record.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "projectId": "project-uuid",
+    "environment": "production",
+    "cache_version": "v1704067200000",
+    "manifest_json": {},
+    "asset_list_json": [],
+    "generated_at": "2024-01-01T00:00:00.000Z",
+    "is_active": true
+  }
+}
+```
+
+**Environment Values:** `dev`, `stage`, `production`
+
+### GET /api/pwa_caches
+
+List PWA cache records.
+
+**Auth:** Required
+
+**Query Parameters:**
+- `projectId` or `project` - Filter by project
+- `environment` - Filter by environment
+- `is_active` - Filter by active status
+
+### GET /api/pwa_caches/:id
+
+Get PWA cache by ID.
+
+**Auth:** Required
+
+**Includes:** project
+
+### PUT /api/pwa_caches/:id
+
+Update PWA cache record.
+
+**Auth:** Required
+
+### DELETE /api/pwa_caches/:id
+
+Delete PWA cache record.
+
+**Auth:** Required
+
+---
+
+## Users Endpoints
+
+### POST /api/users
+
+Create a user.
+
+**Auth:** Required (Admin)
+
+**Request:**
+```json
+{
+  "data": {
+    "email": "newuser@example.com",
+    "password": "password123",
+    "firstName": "John",
+    "lastName": "Doe",
+    "phoneNumber": "+1234567890",
+    "app_roleId": "role-uuid"
+  }
+}
+```
+
+### GET /api/users
+
+List users.
+
+**Auth:** Required
+
+**Searchable Fields:** firstName, lastName, email, phoneNumber
+
+### GET /api/users/:id
+
+Get user by ID.
+
+**Auth:** Required
+
+**Includes:** app_role
+
+### PUT /api/users/:id
+
+Update user.
+
+**Auth:** Required
+
+### DELETE /api/users/:id
+
+Delete user.
+
+**Auth:** Required (Admin)
+
+---
+
+## Roles Endpoints
+
+### POST /api/roles
+
+Create a role.
+
+**Auth:** Required (Admin)
+
+**Request:**
+```json
+{
+  "data": {
+    "name": "Editor",
+    "globalAccess": false
+  }
+}
+```
+
+### GET /api/roles
+
+List roles.
+
+**Auth:** Required
+
+### GET /api/roles/:id
+
+Get role by ID.
+
+**Includes:** permissions
+
+---
+
+## Permissions Endpoints
+
+### POST /api/permissions
+
+Create a permission.
+
+**Auth:** Required (Admin)
+
+**Request:**
+```json
+{
+  "data": {
+    "roleId": "role-uuid",
+    "entity": "projects",
+    "action": "read"
+  }
+}
+```
+
+**Actions:** `create`, `read`, `update`, `delete`
+
+---
+
+## Publishing Endpoints
+
+The platform uses a three-tier publishing workflow:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Constructor (dev)    Stage (preview)     Production (live)     │
+│       dev        ───►    stage       ───►   production          │
+│  "Save to Stage"      "Publish"                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### POST /api/publish/save-to-stage
+
+Copy `dev` content to `stage` for preview. See [Projects Endpoints](#post-apipublishsave-to-stage).
+
+### POST /api/publish (or POST /api/publish/publish)
+
+Publish project from `stage` to `production` environment. Both endpoints are aliases and perform the same action.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "projectId": "project-uuid",
+  "title": "v1.0 Release",
+  "description": "Initial production release"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "publishEventId": "event-uuid",
+  "summary": {
+    "pages_copied": 10,
+    "audios_copied": 2
+  }
+}
+```
+
+**Note:** Publishes `stage` environment content to `production`. Use `save-to-stage` first to copy changes from `dev`. Page elements, navigation links, and transitions are stored within `tour_pages.ui_schema_json` and copied automatically with pages.
+
+---
+
+## Publish Events Endpoints
+
+### GET /api/publish_events
+
+List publish events.
+
+**Auth:** Required
+
+**Query Parameters:**
+- `projectId` - Filter by project
+
+**Response:**
+```json
+{
+  "rows": [
+    {
+      "id": "event-uuid",
+      "projectId": "project-uuid",
+      "title": "v1.0 Release",
+      "description": "Initial release",
+      "publishedAt": "2024-01-01T00:00:00.000Z",
+      "createdBy": "user-uuid"
+    }
+  ],
+  "count": 5
+}
+```
+
+---
+
+## Access Logs Endpoints
+
+### POST /api/access_logs
+
+Create an access log entry.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "project": "project-uuid",
+    "user": "user-uuid",
+    "environment": "production",
+    "path": "/api/tour_pages",
+    "ip_address": "192.168.1.1",
+    "user_agent": "Mozilla/5.0...",
+    "accessed_at": "2024-01-01T00:00:00.000Z"
+  }
+}
+```
+
+**Environment Values:** `admin`, `stage`, `production`
+
+### GET /api/access_logs
+
+List access logs.
+
+**Auth:** Required
+
+**Searchable Fields:** `path`, `ip_address`, `user_agent`
+
+**Query Parameters:**
+- `project` - Filter by project ID or name
+- `user` - Filter by user ID or name
+- `environment` - Filter by environment (admin/stage/production)
+- `accessed_atRange` - Filter by date range
+
+---
+
+## Presigned URL Requests Endpoints
+
+Track and audit presigned URL generation requests.
+
+### POST /api/presigned_url_requests
+
+Create a presigned URL request record.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": {
+    "requested_key": "uploads/projects/abc/image.jpg",
+    "mime_type": "image/jpeg",
+    "status": "pending",
+    "requested_size_mb": 2.5,
+    "expires_at": "2024-01-01T01:00:00.000Z"
+  }
+}
+```
+
+**Status Values:** `pending`, `completed`, `expired`, `failed`
+
+### GET /api/presigned_url_requests
+
+List presigned URL requests.
+
+**Auth:** Required
+
+**Query Parameters:**
+- `status` - Filter by status
+- `requested_key` - Filter by storage key
+
+### GET /api/presigned_url_requests/:id
+
+Get presigned URL request by ID.
+
+**Auth:** Required
+
+### PUT /api/presigned_url_requests/:id
+
+Update presigned URL request.
+
+**Auth:** Required
+
+### DELETE /api/presigned_url_requests/:id
+
+Delete presigned URL request.
+
+**Auth:** Required
+
+---
+
+## Global UI Control Defaults Endpoints
+
+Global UI controls are the system-owned fullscreen, sound, and offline buttons.
+Runtime settings resolve through:
+
+```
+global_ui_control_defaults → project_ui_control_settings → tour_pages.global_ui_controls_settings_json
+```
+
+### GET /api/global-ui-control-defaults
+
+Get singleton platform defaults.
+
+**Auth:** Not required for runtime reads
+
+### PUT /api/global-ui-control-defaults/:id
+
+Update singleton platform defaults.
+
+**Auth:** Required
+
+### GET /api/project-ui-control-settings/project/:projectId/env/:environment
+
+Get project/environment overrides. `environment` is `dev`, `stage`, or
+`production`.
+
+**Auth:** Required for `dev` and `stage`. Production is public for public
+presentations and requires JWT/access grants for private production
+presentations.
+
+### PUT /api/project-ui-control-settings/project/:projectId/env/:environment
+
+Upsert project/environment overrides.
+
+**Auth:** Required
+
+### DELETE /api/project-ui-control-settings/project/:projectId/env/:environment
+
+Delete project/environment overrides so runtime falls back to global defaults.
+
+**Auth:** Required
+
+---
+
+## Element Type Defaults Endpoints
+
+Global platform-wide default settings for each element type. These are the source of truth that get snapshotted to `project_element_defaults` when a project is created.
+
+**Alias:** `/api/ui-elements` routes to the same endpoints as `/api/element-type-defaults`.
+
+**Note:** The Constructor page uses `project_element_defaults` (not this endpoint) to fetch element defaults for the current project. This endpoint is for platform-wide administration of default settings.
+
+### GET /api/element-type-defaults
+
+List all element type defaults.
+
+**Auth:** Required
+
+**Response:**
+```json
+{
+  "rows": [
+    {
+      "id": "uuid",
+      "element_type": "navigation_next",
+      "name": "Navigation: Forward",
+      "sort_order": 1,
+      "is_active": true,
+      "default_settings_json": {
+        "width": "60px",
+        "height": "60px",
+        "opacity": 1
+      }
+    }
+  ],
+  "count": 11
+}
+```
+
+### GET /api/element-type-defaults/:id
+
+Get element type default by ID.
+
+**Auth:** Required
+
+### PUT /api/element-type-defaults/:id
+
+Update element type default settings.
+
+**Auth:** Required (Admin)
+
+**Request:**
+```json
+{
+  "id": "uuid",
+  "data": {
+    "default_settings_json": {
+      "width": "80px",
+      "height": "80px"
+    }
+  }
+}
+```
+
+---
+
+## Project Element Defaults Endpoints
+
+Project-specific default settings for UI elements. These are automatically snapshotted from global defaults (`element_type_defaults`) when a project is created. The Constructor page uses this endpoint to fetch element defaults for the current project.
+
+**Three-Tier Element Defaults Hierarchy:**
+```
+element_type_defaults (global) → project_element_defaults (project) → tour_pages.ui_schema_json (instance)
+```
+
+### GET /api/project-element-defaults
+
+List project element defaults.
+
+**Auth:** Required
+
+**Query Parameters:**
+- `projectId` or `project` - Filter by project ID or name (recommended)
+- Supports `|` pipe separator for multiple values
+
+**Response:**
+```json
+{
+  "rows": [
+    {
+      "id": "uuid",
+      "projectId": "project-uuid",
+      "element_type": "navigation_next",
+      "name": "Navigation: Forward",
+      "sort_order": 1,
+      "settings_json": {
+        "width": "60px",
+        "height": "60px"
+      },
+      "source_element_id": "global-default-uuid",
+      "snapshot_version": 1
+    }
+  ],
+  "count": 11
+}
+```
+
+### GET /api/project-element-defaults/:id
+
+Get project element default by ID.
+
+**Auth:** Required
+
+### PUT /api/project-element-defaults/:id
+
+Update project-specific default settings.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "id": "uuid",
+  "data": {
+    "settings_json": {
+      "width": "100px",
+      "backgroundColor": "#ff0000"
+    }
+  }
+}
+```
+
+### POST /api/project-element-defaults/:id/reset
+
+Reset project default to current global default. Copies settings from `element_type_defaults` and increments `snapshot_version`.
+
+**Auth:** Required
+
+**Response:** Returns the updated project element default record:
+```json
+{
+  "id": "uuid",
+  "projectId": "project-uuid",
+  "element_type": "navigation_next",
+  "name": "Navigation: Forward",
+  "sort_order": 1,
+  "settings_json": { "width": "60px", "height": "60px" },
+  "source_element_id": "global-default-uuid",
+  "snapshot_version": 2,
+  "createdAt": "2024-01-01T00:00:00.000Z",
+  "updatedAt": "2024-01-15T00:00:00.000Z"
+}
+```
+
+**Error:** Returns 500 if global default not found for the element type.
+
+### GET /api/project-element-defaults/:id/diff
+
+Compare project default with current global default.
+
+**Auth:** Required
+
+**Response:**
+```json
+{
+  "projectDefault": {
+    "id": "uuid",
+    "element_type": "navigation_next",
+    "settings_json": { "width": "100px" }
+  },
+  "globalDefault": {
+    "id": "global-uuid",
+    "element_type": "navigation_next",
+    "default_settings_json": { "width": "60px" }
+  },
+  "hasGlobalDefault": true,
+  "isDifferent": true,
+  "projectSettings": { "width": "100px" },
+  "globalSettings": { "width": "60px" }
+}
+```
+
+**Response when global default not found:**
+```json
+{
+  "projectDefault": { ... },
+  "globalDefault": null,
+  "hasGlobalDefault": false,
+  "isDifferent": true
+}
+```
+
+---
+
+## Search Endpoint
+
+### POST /api/search
+
+Search across all entities. Searches both text fields and numeric fields (cast to text for matching).
+
+**Auth:** Required
+
+**Rate Limit:** 30 requests per minute per IP
+
+**Request:**
+```json
+{
+  "searchQuery": "keyword"
+}
+```
+
+**Response:**
+Returns a flat array of matching records from all searchable tables. Each record includes `tableName` and `matchAttribute` fields to identify the source and matching fields.
+
+```json
+[
+  {
+    "id": "uuid-1",
+    "name": "My Project",
+    "slug": "my-project",
+    "tableName": "projects",
+    "matchAttribute": ["name", "slug"]
+  },
+  {
+    "id": "uuid-2",
+    "title": "Home Page",
+    "tableName": "tour_pages",
+    "matchAttribute": ["title"]
+  }
+]
+```
+
+**Searchable Tables & Fields:**
+
+| Table | Text Fields | Numeric Fields |
+|-------|-------------|----------------|
+| `users` | firstName, lastName, phoneNumber, email | - |
+| `projects` | name, slug, description, logo_url, favicon_url, og_image_url | - |
+| `assets` | name, cdn_url, storage_key, mime_type, checksum | size_mb, width_px, height_px, duration_sec |
+| `asset_variants` | cdn_url | width_px, height_px, size_mb |
+| `presigned_url_requests` | requested_key, mime_type, status | requested_size_mb |
+| `tour_pages` | source_key, name, slug, background_image_url, background_video_url, background_audio_url, ui_schema_json | sort_order |
+| `project_audio_tracks` | source_key, name, slug, url | volume, sort_order |
+| `publish_events` | error_message | pages_copied, transitions_copied, audios_copied |
+| `pwa_caches` | cache_version, manifest_json, asset_list_json | - |
+| `access_logs` | path, ip_address, user_agent | - |
+
+**Permission Check:** Search results are filtered based on user permissions. Only tables where user has `READ_{TABLE_NAME}` permission are searched.
+
+**Limit:** Maximum 50 results per table.
+
+---
+
+## Bulk Operations
+
+### POST /api/{entity}/deleteByIds
+
+Bulk delete entities.
+
+**Auth:** Required
+
+**Request:**
+```json
+{
+  "data": ["uuid-1", "uuid-2", "uuid-3"]
+}
+```
+
+**Response:**
+```json
+{
+  "deleted": 3
+}
+```
+
+### POST /api/{entity}/bulk-import
+
+Bulk import from CSV.
+
+**Auth:** Required
+
+**Content-Type:** `multipart/form-data`
+
+**Form Fields:**
+- `file` - CSV file
+- `importHash` - Unique import identifier
+
+**Response:**
+```json
+{
+  "imported": 50,
+  "errors": []
+}
+```
+
+---
+
+## CSV Export
+
+Add `?filetype=csv` to any list endpoint to export as CSV.
+
+**Example:**
+```
+GET /api/projects?filetype=csv&limit=1000
+```
+
+**Response:** CSV file download with appropriate headers
+
+---
+
+## Swagger Documentation
+
+Interactive API documentation available at:
+
+```
+GET /api-docs
+```
+
+Provides Swagger UI with all endpoints, request/response schemas, and testing capabilities.
diff --git a/documentation/asset-upload-variants.md b/documentation/asset-upload-variants.md
new file mode 100644
index 0000000..d9bebcb
--- /dev/null
+++ b/documentation/asset-upload-variants.md
@@ -0,0 +1,1239 @@
+# Asset Upload & Variants
+
+Complete documentation for the Tour Builder Platform's asset management system including chunked uploads, storage providers, and variant tracking.
+
+For persisted media metadata, the backend is the source of truth for video FPS.
+Frontend upload probing is still used for immediate UX, but the asset
+create/update path now probes the stored file with bundled `ffprobe-static` and
+saves actual `frame_rate` metadata on the asset record.
+
+## Overview
+
+The platform implements a **robust asset management system** with:
+- **Chunked uploads** - Large files uploaded in 5MB chunks with resumability
+- **Multi-provider storage** - S3, Google Cloud Storage, or local filesystem
+- **Asset variants** - Metadata tracking for different file formats/sizes
+- **Media probing** - Automatic extraction of duration, dimensions
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Upload Flow                                      │
+│                                                                          │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                 │
+│  │  Frontend   │    │   Backend   │    │   Storage   │                 │
+│  │  Uploader   │───▶│   Service   │───▶│   Provider  │                 │
+│  └─────────────┘    └─────────────┘    └─────────────┘                 │
+│        │                  │                   │                         │
+│        │ Chunks (5MB)     │ Session Mgmt      │ S3/GCloud/Local        │
+│        ▼                  ▼                   ▼                         │
+│   UploadService.js   file.js service     AWS SDK / GCloud SDK         │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      Database Structure                                  │
+│                                                                          │
+│  assets ─────────────────────────────────────────┐                      │
+│     │                                            │                      │
+│     ▼                                            ▼                      │
+│  asset_variants                              projects                   │
+│  (variant_type, cdn_url, dimensions)         (owner)                   │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Download Flow (S3 with Presigned URLs)                │
+│                                                                          │
+│  ┌─────────────┐  1. Get presigned URLs  ┌─────────────┐               │
+│  │  Frontend   │────────────────────────▶│   Backend   │               │
+│  │  Preloader  │◀────────────────────────│  /presign   │               │
+│  └─────────────┘  2. Return signed URLs  └─────────────┘               │
+│        │                                                                 │
+│        │ 3. Direct download (fast)                                      │
+│        ▼                                                                 │
+│  ┌─────────────┐                                                        │
+│  │     S3      │  No backend proxy - assets served directly from S3    │
+│  └─────────────┘                                                        │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Chunked Upload System
+
+### Overview
+
+Large files are uploaded in chunks to handle network interruptions and support resumable uploads.
+
+**Key Parameters:**
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| Chunk Size | 5 MB | `5 * 1024 * 1024` bytes |
+| Max Retries | 3 | Per-chunk retry limit |
+| Retry Backoff | 500ms × retry | Exponential backoff |
+| Session TTL | 24 hours | Expired sessions auto-cleaned |
+
+### Upload Session Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Phase 1: Initialize Session                                              │
+├─────────────────────────────────────────────────────────────────────────┤
+│ POST /file/upload-sessions/init                                          │
+│   Body: { folder, filename, totalChunks, size, contentType }            │
+│   Response: { sessionId, uploadedChunks: [], totalChunks }              │
+│                                                                          │
+│   - Creates UUID session                                                 │
+│   - Stores metadata (local: JSON file, S3: S3 object)                   │
+│   - Triggers cleanup of expired sessions                                 │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Phase 2: Upload Chunks                                                   │
+├─────────────────────────────────────────────────────────────────────────┤
+│ PUT /file/upload-sessions/{sessionId}/chunks/{chunkIndex}               │
+│   Headers: Content-Type: application/octet-stream                       │
+│   Body: <binary chunk data>                                              │
+│   Response: { sessionId, chunkIndex, uploadedChunks, totalChunks }      │
+│                                                                          │
+│   For each chunk (0 to totalChunks-1):                                  │
+│     - Slice file: start = chunkIndex * 5MB, end = min(size, start+5MB)  │
+│     - Send raw binary data                                               │
+│     - Retry up to 3 times with exponential backoff                      │
+│     - Track progress via onProgress callback                            │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Phase 3: Finalize Upload                                                 │
+├─────────────────────────────────────────────────────────────────────────┤
+│ POST /file/upload-sessions/{sessionId}/finalize                          │
+│   Response: { message, privateUrl, url }                                 │
+│                                                                          │
+│   - Verify all chunks exist                                              │
+│   - Assemble chunks into final file                                      │
+│   - Validate assembled size matches declared size                        │
+│   - Upload to final storage location                                     │
+│   - Cleanup session directory/objects                                    │
+│   - Return public and private URLs                                       │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Session Status Check (Resumability)
+
+```http
+GET /file/upload-sessions/{sessionId}
+```
+
+**Response:**
+```json
+{
+  "sessionId": "uuid",
+  "totalChunks": 10,
+  "uploadedChunks": [0, 1, 2, 3],
+  "status": "active"
+}
+```
+
+Use this to resume interrupted uploads by checking which chunks are already uploaded.
+
+### Session Metadata Structure
+
+```javascript
+{
+  id: "uuid",
+  userId: "user-uuid",        // Owner (enforced on all operations)
+  folder: "assets/project-id",
+  filename: "uuid.mp4",
+  totalChunks: 10,
+  size: 52428800,             // 50MB
+  contentType: "video/mp4",
+  uploadedChunks: [0, 1, 2],  // Completed chunk indices
+  status: "active",
+  createdAt: "2025-01-01T00:00:00Z",
+  updatedAt: "2025-01-01T00:05:00Z"
+}
+```
+
+### Session Storage Locations
+
+Session management is handled by `UploadSessionManager` class (`backend/src/services/file/UploadSessionManager.ts`).
+
+**Local Storage:**
+```
+{uploadDir}/upload_sessions/{sessionId}/
+├── meta.json                 # Session metadata
+└── chunks/
+    ├── 0.part               # Chunk 0
+    ├── 1.part               # Chunk 1
+    └── ...
+```
+
+**S3 Storage:**
+```
+{prefix}/_upload_sessions/{sessionId}/
+├── meta.json                 # Session metadata
+└── chunks/
+    ├── 0.part               # Chunk 0
+    ├── 1.part               # Chunk 1
+    └── ...
+```
+
+### Chunk Assembly
+
+During finalization, chunks are assembled in a temp directory:
+
+```javascript
+// Temp assembly location
+const tempDir = path.join(config.uploadDir, '_temp_assembly');
+const assembledPath = path.join(tempDir, `${sessionId}.bin`);
+
+// For each chunk, append to assembled file
+for (let chunkIndex = 0; chunkIndex < totalChunks; chunkIndex++) {
+  await streamAppendFile(assembledPath, chunkPath);
+}
+
+// Validate size
+if (assembledStats.size !== session.size) {
+  throw new Error('Assembled file size mismatch');
+}
+```
+
+## Storage Providers
+
+### Modular File Service Architecture
+
+The file service uses a **Strategy Pattern** with modular providers:
+
+```
+backend/src/services/
+├── file.js                          # Unified interface (provider initialization, routing)
+└── file/
+    ├── index.js                     # Module exports
+    ├── BaseStorageProvider.ts       # Abstract base class
+    ├── S3StorageProvider.ts         # AWS S3 implementation
+    ├── LocalStorageProvider.ts      # Local filesystem implementation
+    └── UploadSessionManager.ts      # Chunked upload session management
+```
+
+### External Storage Circuit Breaker
+
+The unified file service protects S3/GCloud operations used by media processing
+with an in-process circuit breaker. Local filesystem storage is not breaker
+limited, which keeps local development and simple VM filesystem access direct.
+The values are validated in `backend/src/utils/env-validation.ts` and exposed
+through `config.resilience.fileStorage.breaker`; service code does not read
+these environment variables directly.
+
+Protected operations:
+
+- `downloadToBuffer`
+- `downloadToTempFile`
+- `uploadBuffer`
+- `deleteFile`
+
+Configuration overrides:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FILE_STORAGE_BREAKER_FAILURE_THRESHOLD` | `5` | Consecutive failures before the breaker opens |
+| `FILE_STORAGE_BREAKER_COOLDOWN_MS` | `30000` | Cooldown before a half-open probe is allowed |
+| `FILE_STORAGE_BREAKER_SUCCESS_THRESHOLD` | `2` | Half-open successes required to close the breaker |
+
+When the breaker is open, protected operations fail fast with a `503`-status
+error instead of piling more requests onto the external storage provider.
+
+### Provider Selection Logic
+
+**File:** `backend/src/services/file.ts`
+
+```javascript
+const getFileStorageProvider = () => {
+  // 1. Explicit override from validated backend config
+  const provider = config.fileStorage.provider;
+  if (provider === 's3' || provider === 'gcloud' || provider === 'local') {
+    return provider;
+  }
+
+  // 2. Auto-detect S3 from credentials
+  const hasS3 = Boolean(
+    config.s3.bucket && config.s3.region &&
+    config.s3.accessKeyId && config.s3.secretAccessKey
+  );
+  if (hasS3) return 's3';
+
+  // 3. Auto-detect GCloud from credentials
+  const hasGCloud = Boolean(
+    config.gcloud.projectId &&
+      config.gcloud.clientEmail &&
+      config.gcloud.privateKey &&
+      config.gcloud.bucket &&
+      config.gcloud.hash
+  );
+  if (hasGCloud) return 'gcloud';
+
+  // 4. Default to local filesystem
+  return 'local';
+};
+```
+
+`FILE_STORAGE_PROVIDER` is trimmed/lowercased and validated in
+`backend/src/utils/env-validation.ts`; runtime service code reads
+`config.fileStorage.provider` only.
+
+### S3 Configuration
+
+**Environment Variables:**
+```bash
+FILE_STORAGE_PROVIDER=s3
+AWS_S3_BUCKET=your-bucket-name
+AWS_S3_REGION=us-east-1           # Default: us-east-1
+AWS_ACCESS_KEY_ID=AKIA...
+AWS_SECRET_ACCESS_KEY=secret...
+AWS_S3_PREFIX=optional-prefix     # Default: afeefb9d49f5b7977577876b99532ac7
+```
+
+**Implementation:**
+```javascript
+const initS3 = () => {
+  const client = new S3Client({
+    region: config.s3.region,
+    credentials: {
+      accessKeyId: config.s3.accessKeyId,
+      secretAccessKey: config.s3.secretAccessKey,
+    },
+  });
+
+  return {
+    client,
+    bucket: config.s3.bucket,
+    region: config.s3.region,
+    prefix: config.s3.prefix,
+  };
+};
+```
+
+**URL Format:**
+```
+https://{bucket}.s3.{region}.amazonaws.com/{prefix}/{folder}/{filename}
+```
+
+**SDK:** AWS SDK v3 (`@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`). The TypeScript provider uses official AWS SDK command/config/exception types and shared project storage contracts from `backend/src/types/file.ts`.
+
+### Google Cloud Storage Configuration
+
+**Environment Variables:**
+```bash
+FILE_STORAGE_PROVIDER=gcloud
+GC_PROJECT_ID=your-project-id
+GC_CLIENT_EMAIL=service-account@project.iam.gserviceaccount.com
+GC_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."
+```
+
+**Config (config.ts):** Currently hardcoded values:
+```javascript
+gcloud: {
+  bucket: "fldemo-files",
+  hash: "afeefb9d49f5b7977577876b99532ac7"
+}
+```
+
+**Note:** Unlike S3, GCloud bucket and hash are hardcoded in `config.ts`. To use different values, modify the config file directly.
+
+**URL Format:**
+```
+https://storage.googleapis.com/{bucket}/{hash}/{folder}/{filename}
+```
+
+**SDK:** `@google-cloud/storage`
+
+### Local Storage Configuration
+
+**Default behavior** when no cloud credentials are configured.
+
+**Upload Directory:** `os.tmpdir()` (OS temp directory)
+
+**URL Format:**
+```
+/api/file/download?privateUrl={encodedPath}
+```
+
+Files are served via the backend download endpoint. Note: The download endpoint does **not** require authentication.
+
+## Asset Database Models
+
+### Assets Model
+
+**File:** `backend/src/db/models/assets.js`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | UUID | Yes | Primary key |
+| name | TEXT(255) | No | Display name |
+| asset_type | ENUM | Yes | `image`, `video`, `audio`, `file` |
+| type | ENUM | Yes | `icon`, `background_image`, `audio`, `video`, `transition`, `logo`, `favicon`, `document`, `general` (default) |
+| cdn_url | TEXT | No | Public CDN/storage URL |
+| storage_key | TEXT | No | Private storage path |
+| mime_type | TEXT | No | MIME type (validated format) |
+| size_mb | DECIMAL | No | File size in MB |
+| width_px | INTEGER | No | Image/video width |
+| height_px | INTEGER | No | Image/video height |
+| duration_sec | DECIMAL | No | Video/audio duration |
+| frame_rate | DECIMAL | No | Video FPS from backend `ffprobe` |
+| checksum | TEXT | No | File checksum |
+| is_public | BOOLEAN | Yes | Public visibility (default: false) |
+| projectId | UUID | Yes | FK to projects (CASCADE) |
+
+**Indexes:** `projectId`, `asset_type`, `type`, `is_public`, `deletedAt`
+
+**Note on Environment Scoping:** Assets are scoped to projects, NOT environments. Unlike `tour_pages` which have `dev`, `stage`, and `production` versions, assets are shared across all environments within a project. When pages are published (dev → stage → production), the same asset URLs are used - only the page content (`ui_schema_json`) is copied between environments.
+
+### Asset Variants Model
+
+**File:** `backend/src/db/models/asset_variants.js`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | UUID | Yes | Primary key |
+| variant_type | ENUM | No | `thumbnail`, `preview`, `webp`, `mp4_low`, `mp4_high`, `original` |
+| cdn_url | TEXT(2048) | No | Variant CDN URL (validated URL format) |
+| width_px | INTEGER | No | Variant width |
+| height_px | INTEGER | No | Variant height |
+| size_mb | DECIMAL | No | Variant file size |
+| assetId | UUID | Yes | FK to assets (CASCADE) |
+
+**Variant Types:**
+| Type | Description | Use Case |
+|------|-------------|----------|
+| `thumbnail` | Small preview image | List views, galleries |
+| `preview` | Medium quality preview | Quick previews |
+| `webp` | WebP format | Web optimization |
+| `mp4_low` | Low bitrate video | Mobile, slow connections |
+| `mp4_high` | High bitrate video | Desktop, fast connections |
+| `original` | Unmodified original | Full quality access |
+| `reversed` | FFmpeg-reversed video | Back navigation transitions |
+
+**Note:** Most variants are **metadata records only** - the system tracks variant information but does not auto-generate them. The exception is `reversed` variants, which are auto-generated by the server when a page with transition videos is saved.
+
+**Critical:** The `assetId` field must be properly set when creating variant records. Without it, the variant becomes an orphaned record that cannot be found when looking up an asset's variants via the `asset_variants_asset` association. This is handled in `Asset_variantsDBApi.getFieldMapping()` which must include `assetId` in the field mapping.
+
+### Reversed Video Variant
+
+Reversed videos are a special variant type generated server-side for back navigation transitions. They use a different storage path pattern than other assets.
+
+**Storage Patterns:**
+| Asset Type | Storage Path Pattern | Example |
+|------------|---------------------|---------|
+| Primary assets | `assets/{projectId}/{uuid}.ext` | `assets/abc-123/def-456.mp4` |
+| Reversed videos | `assets/{assetId}/reversed.mp4` | `assets/xyz-789/reversed.mp4` |
+
+**Key Difference:** Reversed videos use the **asset ID** (not project ID) in their path. This is because they are tied to a specific asset (the transition video), not just the project.
+
+**Generation Flow:**
+1. User adds transition video to navigation element
+2. User saves the tour page
+3. Server detects `transitionVideoUrl` in navigation elements
+4. Server generates reversed video using FFmpeg
+5. Reversed video uploaded to `assets/{assetId}/reversed.mp4`
+6. `reverseVideoUrl` populated in `ui_schema_json`
+
+**Note:** Not all assets have reversed videos - only transition videos used in navigation elements.
+
+## Frontend Upload Implementation
+
+### useAssetUploader Hook
+
+**File:** `frontend/src/components/Assets/useAssetUploader.ts`
+
+```typescript
+interface UseAssetUploaderOptions {
+  selectedProjectId: string;
+  onUploadComplete: () => void;
+}
+
+interface UseAssetUploaderReturn {
+  uploadingSections: string[];
+  uploadQueues: Record<string, UploadQueueItem[]>;
+  runBatchUpload: (section: AssetSection, files: File[]) => Promise<void>;
+}
+```
+
+**Key Features:**
+- **Batch upload** with queue management
+- **2 concurrent uploads** maximum (`maxConcurrent = 2`)
+- **Per-file progress** tracking
+- **Abortable** via AbortController
+- **Media probing** for video/audio duration and dimensions
+
+**Status States:**
+| Status | Description |
+|--------|-------------|
+| `queued` | File in queue, waiting to upload |
+| `uploading` | Actively uploading chunks |
+| `saving` | Finalizing upload and creating asset record |
+| `success` | Upload and save completed |
+| `error` | Upload failed (error message available) |
+
+### UploadService Class
+
+**File:** `frontend/src/components/Uploaders/UploadService.js`
+
+**Single File Upload:**
+```javascript
+const result = await FileUploader.upload(path, file, schema);
+// Returns: { id, name, sizeInBytes, privateUrl, publicUrl, new: true }
+```
+
+**Chunked Upload:**
+```javascript
+const result = await FileUploader.uploadChunked(
+  'assets/project-id',  // path
+  file,                  // File object
+  {},                    // schema (validation)
+  {
+    chunkSize: 5 * 1024 * 1024,  // 5MB
+    maxRetries: 3,
+    signal: abortController.signal,
+    onProgress: (percent, { chunkIndex, totalChunks }) => {},
+    onStatus: (status, details) => {},
+  }
+);
+```
+
+### Media Duration Probing
+
+**File:** `frontend/src/lib/mediaDuration.ts`
+
+After upload, video/audio files are probed for metadata:
+
+```typescript
+interface MediaDurationResult {
+  duration: number;
+  width?: number;   // Video only
+  height?: number;  // Video only
+}
+
+// Probe video
+const result = await probeMediaDuration(file, 'video', 10000);
+// Returns: { duration: 120.5, width: 1920, height: 1080 }
+
+// Probe audio
+const result = await probeMediaDuration(file, 'audio', 10000);
+// Returns: { duration: 180.0 }
+```
+
+**Implementation:**
+- Creates HTML5 `<video>` or `<audio>` element
+- Sets `preload="metadata"` for efficiency
+- Listens for `loadedmetadata` event
+- Extracts `duration`, `videoWidth`, `videoHeight`
+- 10-second timeout to prevent hanging
+- Cleans up blob URLs after probing
+
+### Complete Upload Flow
+
+```
+1. User selects files
+   └─ useAssetUploader.runBatchUpload(section, files)
+
+2. Create queue items with status 'queued'
+   └─ Each file gets unique ID
+
+3. For each file (max 2 concurrent):
+   ├─ Status: 'uploading'
+   ├─ Build validation schema from section.assetFormat
+   │   └─ { assetType: 'image' | 'video' | 'audio' }
+   ├─ Call UploadService.uploadChunked()
+   │   ├─ Validate file against schema (MIME type + extension)
+   │   │   └─ Throws Error if validation fails
+   │   ├─ POST /api/file/upload-sessions/init
+   │   ├─ For each chunk:
+   │   │   └─ PUT /api/file/upload-sessions/{sessionId}/chunks/{index}
+   │   ├─ Status: 'saving' (triggered by onStatus('finalizing'))
+   │   └─ POST /api/file/upload-sessions/{sessionId}/finalize
+   │
+   ├─ Probe media duration (video/audio only)
+   │   └─ probeMediaDuration(file, 'video'/'audio')  // Uses local File object
+   │
+   ├─ POST /api/assets
+   │   ├─ Create asset record with metadata
+   │   └─ Backend validates asset_type matches mime_type
+   │
+   └─ Status: 'success'
+
+4. onUploadComplete() callback
+   └─ Refresh asset list
+```
+
+The Assets page refreshes the full selected project's asset list after uploads
+and deletions. It does not apply a frontend `limit` to the `/assets` query;
+assets are filtered into UI sections client-side by `asset_type`, `type`, and
+legacy name tags.
+
+**Validation Layers:**
+1. **Frontend (immediate):** UploadService validates file type before upload starts
+2. **Backend (on asset creation):** AssetsService validates MIME type consistency
+
+**Note:** The 'saving' status is set when the finalize step begins, before the actual finalize request completes.
+
+## API Endpoints
+
+**Note:** All file endpoints are mounted at `/api/file/...`. The frontend axios client has a baseURL of `/api`, so frontend code uses `/file/...` paths which resolve to `/api/file/...`.
+
+### File Upload Endpoints
+
+```http
+# Initialize chunked upload session
+POST /api/file/upload-sessions/init
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "folder": "assets/project-uuid",
+  "filename": "video.mp4",
+  "totalChunks": 10,
+  "size": 52428800,
+  "contentType": "video/mp4"
+}
+
+# Response
+{
+  "sessionId": "uuid",
+  "uploadedChunks": [],
+  "totalChunks": 10
+}
+```
+
+```http
+# Upload single chunk
+PUT /api/file/upload-sessions/{sessionId}/chunks/{chunkIndex}
+Content-Type: application/octet-stream
+Authorization: Bearer {token}
+
+<binary chunk data>
+
+# Response (uploadedChunks is COUNT, not array)
+{
+  "sessionId": "uuid",
+  "chunkIndex": 0,
+  "uploadedChunks": 1,
+  "totalChunks": 10
+}
+```
+
+```http
+# Check session status
+GET /api/file/upload-sessions/{sessionId}
+Authorization: Bearer {token}
+
+# Response (uploadedChunks is ARRAY of chunk indices)
+{
+  "sessionId": "uuid",
+  "totalChunks": 10,
+  "uploadedChunks": [0, 1, 2, 3],
+  "status": "active"
+}
+```
+
+```http
+# Finalize upload
+POST /api/file/upload-sessions/{sessionId}/finalize
+Authorization: Bearer {token}
+
+# Response
+{
+  "message": "Uploaded the file successfully: assets/project-uuid/uuid.mp4",
+  "privateUrl": "assets/project-uuid/uuid.mp4",
+  "url": "https://bucket.s3.region.amazonaws.com/prefix/assets/project-uuid/uuid.mp4"
+}
+```
+
+```http
+# Download file (local storage) - NO authentication required
+GET /api/file/download?privateUrl={encodedPath}
+```
+
+**Note:** The download endpoint does not require JWT authentication, allowing public access to files. Access control should be implemented at the application level if needed.
+
+### Presigned URL Endpoint (S3 Direct Download)
+
+For S3 storage, the platform supports presigned URLs for direct browser-to-S3 downloads, bypassing the backend proxy for improved performance.
+
+```http
+# Generate presigned URLs for batch of assets
+POST /api/file/presign
+Content-Type: application/json
+
+{
+  "urls": [
+    "assets/project-uuid/video1.mp4",
+    "assets/project-uuid/image1.jpg",
+    "assets/project-uuid/video2.mp4"
+  ]
+}
+
+# Response
+{
+  "presignedUrls": {
+    "assets/project-uuid/video1.mp4": "https://bucket.s3.region.amazonaws.com/prefix/assets/project-uuid/video1.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=...&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=...",
+    "assets/project-uuid/image1.jpg": "https://bucket.s3.region.amazonaws.com/prefix/assets/project-uuid/image1.jpg?...",
+    "assets/project-uuid/video2.mp4": "https://bucket.s3.region.amazonaws.com/prefix/assets/project-uuid/video2.mp4?..."
+  }
+}
+```
+
+**Key Details:**
+- **Max URLs per request:** 50
+- **URL expiry:** 1 hour (3600 seconds)
+- **Fallback:** For non-S3 providers (GCloud, local), returns backend proxy URLs
+- **No authentication required:** Similar to download endpoint
+
+**Benefits:**
+| Aspect | Backend Proxy | Presigned URLs |
+|--------|---------------|----------------|
+| Download speed | Slower (proxied) | Direct S3 access |
+| Backend load | Proxies all bytes | Only generates URLs |
+| Scalability | Backend bottleneck | S3 handles traffic |
+
+**Frontend Integration:**
+
+The frontend implements a multi-layer caching strategy:
+
+1. **Presigned URL Cache** (`lib/assetUrl.ts`) - In-memory cache with 1-hour TTL, refreshing 5 minutes before expiry
+2. **Cache API Storage** (`StorageManager`) - Browser Cache API for persistent storage of downloaded assets
+3. **Ready Blob URL Map** (`usePreloadOrchestrator`) - Pre-decoded blob URLs for instant display
+
+**Presigned URL Batching:**
+
+The `assetUrl.ts` module implements automatic batching for presigned URL requests:
+- `queuePresignedUrl(key)` - Queue single key for batch
+- `queuePresignedUrls(keys)` - Queue multiple keys at once
+- `flushPresignedUrlQueue()` - Flush pending batch immediately
+- `getPresignedUrl(key)` - Synchronous cache lookup
+- `clearPresignedUrlCache()` - Clear all cached URLs
+- Batch delay: 10ms (collects requests before sending)
+- Automatic deduplication of keys
+- Returns cached URLs immediately if valid
+
+**Presigned URL Verification:**
+
+Before using presigned URLs for playback, the system verifies they work:
+- `presignedUrlsVerified` flag - Tracks if presigned URLs are confirmed working
+- `markPresignedUrlsVerified()` - Called by preloader after successful S3 fetch
+- `resolveAssetPlaybackUrl()` returns proxy URLs until presigned URLs are verified
+- This prevents CORS errors from breaking playback on first load
+
+**Utility Functions:**
+
+| Function | Purpose |
+|----------|---------|
+| `isRelativeStoragePath(url)` | Check if path is relative (not http/blob/data URL) |
+| `extractStoragePath(url)` | Extract relative path from full S3 URL |
+| `resolveAssetPlaybackUrl(value)` | Resolve any asset path to playable URL |
+| `arePresignedUrlsDisabled()` | Check if presigned URLs are disabled |
+| `markPresignedUrlFailed(key)` | Mark presigned URL failed, disable globally |
+
+**CORS Failure Detection:**
+
+The module includes automatic CORS failure detection via Axios interceptor:
+- `setupPresignedUrlInterceptor()` - Sets up Axios response interceptor
+- Detects presigned S3 URL failures (likely CORS issues)
+- Automatically disables presigned URLs and falls back to proxy URLs
+- `presignedUrlsDisabled` flag prevents further presigned URL attempts
+
+**Complete Preload-to-Display Flow:**
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                     Asset Preloading Pipeline                            │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  1. Batch fetch presigned URLs                                          │
+│     POST /api/file/presign { urls: [...] }                              │
+│                     ↓                                                    │
+│  2. Download assets from S3 (parallel, with progress)                   │
+│     fetch(presignedUrl) → Response blob                                 │
+│                     ↓                                                    │
+│  3. Store in Cache API (persistent)                                     │
+│     caches.open('assets').put(originalUrl, blob)                        │
+│                     ↓                                                    │
+│  4. Create blob URL (local reference)                                   │
+│     URL.createObjectURL(blob) → blob:...                                │
+│                     ↓                                                    │
+│  5. Pre-decode if image (paint-ready)                                   │
+│     new Image().decode() on blob URL                                    │
+│                     ↓                                                    │
+│  6. Store in readyBlobUrls Map                                          │
+│     readyBlobUrlsRef.current.set(originalUrl, blobUrl)                  │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+
+Page Navigation (instant):
+  getReadyBlobUrl(originalUrl)  → O(1) Map lookup
+  return decodedBlobUrl         → Already paint-ready
+  set as background             → No delay, no flash
+```
+
+**Key Methods:**
+| Method | Purpose |
+|--------|---------|
+| `getReadyBlobUrl(url)` | O(1) instant lookup for pre-decoded blob URL (accepts storage key or resolved URL) |
+| `getCachedBlobUrl(url)` | Async fallback - creates blob URL from Cache API (accepts storage key or resolved URL) |
+| `isUrlPreloaded(url)` | Check if asset is ready for instant display |
+
+**Storage Key Mapping:**
+
+Assets are stored under multiple keys for reliable cache lookup:
+
+| Key Type | Example | Purpose |
+|----------|---------|---------|
+| Download URL | `https://s3...?X-Amz-Signature=ABC` | Original presigned URL used for download |
+| Storage Key | `assets/project-123/video.mp4` | Canonical path (most reliable for lookups) |
+| Proxy URL | `/api/file/download?privateUrl=...` | Fallback compatibility |
+
+**Why storage keys matter:**
+- Presigned URL signatures change on each resolution (X-Amz-Signature differs)
+- Storage keys are canonical and never change
+- Lookups prioritize storage key for reliable cache hits across URL regeneration
+- After page refresh, Cache API lookup by storage key still works
+
+```
+Lookup Priority:
+1. getReadyBlobUrl(storageKey)   → instant O(1) Map lookup (same session)
+2. getCachedBlobUrl(storageKey)  → Cache API lookup (~5ms, post-refresh)
+3. getReadyBlobUrl(resolvedUrl)  → fallback by resolved URL
+4. getCachedBlobUrl(resolvedUrl) → fallback by resolved URL
+5. Network fetch                 → last resort
+```
+
+**Memory Management:** Blob URLs are revoked on unmount via `clearReadyBlobUrls()` to prevent memory leaks.
+
+**S3 CORS Configuration Required:**
+
+For presigned URLs to work, the S3 bucket must have CORS configured:
+
+```json
+[
+  {
+    "AllowedHeaders": ["*"],
+    "AllowedMethods": ["GET", "HEAD"],
+    "AllowedOrigins": [
+      "https://*.dev.flatlogic.app",
+      "https://*.flatlogic.app",
+      "http://localhost:3000"
+    ],
+    "ExposeHeaders": ["Content-Length", "Content-Type", "ETag"],
+    "MaxAgeSeconds": 3600
+  }
+]
+```
+
+**Note:** S3 CORS requires exact origin matching or wildcard patterns (`*` only at the beginning). Add your specific subdomain or use wildcards like `https://*.dev.flatlogic.app` for multiple environments.
+
+**Apply via AWS CLI:**
+```bash
+aws s3api put-bucket-cors --bucket YOUR_BUCKET_NAME --cors-configuration file://cors.json
+```
+
+### Asset CRUD Endpoints
+
+```http
+# Create asset record
+POST /api/assets
+Authorization: Bearer {token}
+
+{
+  "data": {
+    "project": "project-uuid",
+    "name": "background.mp4",
+    "asset_type": "video",
+    "type": "background_image",
+    "cdn_url": "https://...",
+    "storage_key": "assets/project-uuid/uuid.mp4",
+    "mime_type": "video/mp4",
+    "size_mb": 50.0,
+    "duration_sec": 120.5,
+    "width_px": 1920,
+    "height_px": 1080,
+    "frame_rate": 23.976,
+    "is_public": false
+  }
+}
+```
+
+Asset creation accepts the project relation as `data.project` from frontend
+forms. `AssetsDBApi.getFieldMapping()` also maps this to `projectId`, and the
+generic DB API invokes the Sequelize `setProject` association setter with the
+created asset record as its method context. This is required because Sequelize
+belongsTo mixins call `this.set(...)` internally; detached setter calls fail
+before the project foreign key can be persisted.
+
+```http
+# List assets
+GET /api/assets?project={projectId}&asset_type=video
+Authorization: Bearer {token}
+```
+
+```http
+# Create asset variant
+POST /api/asset_variants
+Authorization: Bearer {token}
+
+{
+  "data": {
+    "asset": "asset-uuid",
+    "variant_type": "mp4_low",
+    "cdn_url": "https://...",
+    "width_px": 854,
+    "height_px": 480,
+    "size_mb": 10.0
+  }
+}
+```
+
+## Security & Validation
+
+### Backend Validation
+
+**Folder Sanitization:**
+```javascript
+const sanitizeFolder = (folder) => {
+  const value = String(folder || '').trim().replace(/^\/+|\/+$/g, '');
+  if (!value || value.includes('..')) return null;  // Prevent path traversal
+  return value;
+};
+```
+
+**Filename Sanitization:**
+```javascript
+const sanitizeFilename = (filename) => {
+  const value = path.basename(String(filename || '').trim());
+  if (!value || value === '.' || value === '..') return null;
+  return value;
+};
+```
+
+**Session Ownership:**
+- Session tied to `req.currentUser.id`
+- All session operations verify `session.userId === req.currentUser.id`
+- Unauthorized access returns HTTP 403
+
+**Chunk Validation:**
+- Chunk index bounds checking (`chunkIndex < totalChunks`)
+- File size consistency (`assembledSize === declaredSize`)
+
+### Frontend Validation
+
+**File:** `frontend/src/components/Uploaders/UploadService.js`
+
+The UploadService validates files before upload using both MIME type prefixes and file extensions as fallback.
+
+```javascript
+// Valid MIME type prefixes and extensions for each asset type
+const VALID_MIME_TYPES = {
+  image: {
+    prefixes: ['image/'],
+    extensions: ['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'bmp', 'ico'],
+  },
+  video: {
+    prefixes: ['video/'],
+    extensions: ['mp4', 'webm', 'mov', 'avi', 'mkv', 'm4v', 'ogv'],
+  },
+  audio: {
+    prefixes: ['audio/'],
+    extensions: ['mp3', 'wav', 'ogg', 'aac', 'm4a', 'flac', 'weba'],
+  },
+};
+
+static validate(file, schema) {
+  // Asset type validation (unified approach)
+  if (schema.assetType) {
+    const result = validateAssetType(file, schema.assetType);
+    if (!result.valid) {
+      throw new Error(result.error);
+    }
+  }
+
+  // Legacy image validation
+  if (schema.image) {
+    const result = validateAssetType(file, 'image');
+    if (!result.valid) {
+      throw new Error('You must upload an image');
+    }
+  }
+
+  // Legacy video validation
+  if (schema.video) {
+    const result = validateAssetType(file, 'video');
+    if (!result.valid) {
+      throw new Error('You must upload a video');
+    }
+  }
+
+  // Legacy audio validation
+  if (schema.audio) {
+    const result = validateAssetType(file, 'audio');
+    if (!result.valid) {
+      throw new Error('You must upload an audio file');
+    }
+  }
+
+  // Size limit
+  if (schema.size && file.size > schema.size) {
+    const maxSizeMB = (schema.size / (1024 * 1024)).toFixed(1);
+    const fileSizeMB = (file.size / (1024 * 1024)).toFixed(1);
+    throw new Error(`File is too big. Maximum ${maxSizeMB}MB, got ${fileSizeMB}MB`);
+  }
+
+  // Extension whitelist
+  if (schema.formats && !schema.formats.includes(extension)) {
+    throw new Error(`Invalid format. Allowed: ${schema.formats.join(', ')}`);
+  }
+}
+```
+
+**Validation Schemas:**
+
+| Schema Property | Description |
+|-----------------|-------------|
+| `assetType` | Asset type: `'image'`, `'video'`, or `'audio'` (unified validation) |
+| `image` | Legacy: Must be an image file |
+| `video` | Legacy: Must be a video file |
+| `audio` | Legacy: Must be an audio file |
+| `size` | Maximum file size in bytes |
+| `formats` | Allowed file extensions array |
+
+**Fallback Logic:**
+Validation checks MIME type prefix first, then falls back to file extension. This handles cases where browsers don't report MIME type correctly.
+
+### Backend Asset Service Validation
+
+**File:** `backend/src/services/assets.ts`
+
+The AssetsService validates that `asset_type` and `mime_type` are consistent when creating or updating assets.
+
+```typescript
+const VALID_MIME_PATTERNS = {
+  image: {
+    prefixes: ['image/'],
+    description: 'image (jpeg, png, gif, webp, svg, etc.)',
+  },
+  video: {
+    prefixes: ['video/'],
+    description: 'video (mp4, webm, mov, etc.)',
+  },
+  audio: {
+    prefixes: ['audio/'],
+    description: 'audio (mp3, wav, ogg, etc.)',
+  },
+};
+
+// Throws ValidationError if mime_type doesn't match asset_type
+const validation = validateAssetMimeType(assetType, mimeType);
+if (!validation.valid) {
+  throw new ValidationError(validation.error);
+}
+```
+
+**Validation Rules:**
+- On `create()`: Always validates `asset_type` and `mime_type` match
+- On `update()`: Only validates if both `asset_type` AND `mime_type` are provided
+- Skips validation if `asset_type` is not `image`, `video`, or `audio`
+- Skips validation if `mime_type` is missing (browser may not send it)
+
+**Error Response:**
+```json
+{
+  "code": 400,
+  "message": "Invalid file type for video. Expected video (mp4, webm, mov, etc.), got \"image/jpeg\""
+}
+```
+
+---
+
+### MIME Type Validation (DB Level)
+
+```javascript
+mime_type: {
+  type: DataTypes.TEXT,
+  validate: {
+    is: {
+      args: /^[a-z0-9]+\/[a-z0-9.+-]+$/i,
+      msg: 'Invalid MIME type format'
+    },
+  },
+}
+```
+
+## Variant Selection for PWA
+
+**File:** `backend/src/services/pwa_manifest.js`
+
+Variants are selected based on device type for PWA offline caching:
+
+```javascript
+static selectVariants(variants, deviceType) {
+  const priority = deviceType === 'mobile'
+    ? ['mp4_low', 'webp', 'thumbnail', 'preview', 'mp4_high', 'original']
+    : ['mp4_high', 'webp', 'preview', 'mp4_low', 'thumbnail', 'original'];
+
+  // Select first matching variant by priority
+  for (const type of priority) {
+    const variant = variants.find(v => v.variant_type === type);
+    if (variant) return [variant];
+  }
+  return [];
+}
+```
+
+**Device Priorities:**
+| Device | Priority Order |
+|--------|----------------|
+| Mobile | `mp4_low` > `webp` > `thumbnail` > `preview` > `mp4_high` > `original` |
+| Desktop | `mp4_high` > `webp` > `preview` > `mp4_low` > `thumbnail` > `original` |
+
+## Session Cleanup
+
+### Automatic Cleanup
+
+Expired sessions (>24 hours old) are automatically cleaned up:
+
+**Local Storage:**
+```javascript
+// Called synchronously on initUploadSession
+cleanupExpiredUploadSessions();
+```
+
+**S3 Storage:**
+```javascript
+// Called asynchronously (non-blocking)
+cleanupExpiredS3UploadSessions().catch(err =>
+  console.error('S3 session cleanup failed', err)
+);
+```
+
+### Manual Cleanup
+
+For stuck sessions, directly remove:
+
+**Local:**
+```bash
+rm -rf {uploadDir}/upload_sessions/{sessionId}/
+```
+
+**S3:**
+```bash
+aws s3 rm --recursive s3://{bucket}/{prefix}/_upload_sessions/{sessionId}/
+```
+
+## File Reference
+
+### Backend Files
+
+| File | Purpose |
+|------|---------|
+| `backend/src/services/file.ts` | Unified file storage service with provider initialization |
+| `backend/src/services/file/index.ts` | Module exports for file service |
+| `backend/src/services/file/BaseStorageProvider.ts` | Abstract base class for storage providers |
+| `backend/src/services/file/S3StorageProvider.ts` | AWS S3 storage implementation |
+| `backend/src/services/file/LocalStorageProvider.ts` | Local filesystem storage implementation |
+| `backend/src/services/file/UploadSessionManager.ts` | Chunked upload session management |
+| `backend/src/routes/file.js` | File API endpoints |
+| `backend/src/db/models/assets.js` | Assets model |
+| `backend/src/db/models/asset_variants.js` | Asset variants model |
+| `backend/src/db/api/assets.ts` | Assets DB operations |
+| `backend/src/services/assets.ts` | Assets service validation and media metadata enrichment |
+| `backend/src/db/api/asset_variants.ts` | Variants DB operations |
+| `backend/src/services/pwa_manifest.js` | PWA manifest with variant selection |
+| `backend/src/config.ts` | Storage provider configuration |
+
+### Frontend Files
+
+| File | Purpose |
+|------|---------|
+| `frontend/src/components/Assets/useAssetUploader.ts` | Upload hook |
+| `frontend/src/components/Uploaders/UploadService.js` | Upload service class |
+| `frontend/src/lib/mediaDuration.ts` | Media metadata probing |
+| `frontend/src/lib/assetUrl.ts` | Asset URL resolution with presigned URL cache |
+| `frontend/src/lib/offline/StorageManager.ts` | Cache API abstraction for asset storage (small files) and IndexedDB (large files ≥5MB) |
+| `frontend/src/hooks/usePreloadOrchestrator.ts` | Asset preloading with presigned URL batch fetching and blob URL management |
+| `frontend/src/hooks/usePageSwitch.ts` | Page navigation using preloaded blob URLs for instant transitions |
+
+## Troubleshooting
+
+### Upload Stuck at "Finalizing"
+
+1. Check backend logs for assembly errors
+2. Verify all chunks were uploaded: `GET /file/upload-sessions/{sessionId}`
+3. Check disk space for temp assembly directory
+4. Verify storage provider credentials
+
+### "Upload Session Not Found" Error
+
+1. Session expired (>24 hours) - restart upload
+2. Session cleaned up - check for concurrent cleanup
+3. Wrong sessionId - verify client-side tracking
+
+### "Assembled File Size Mismatch" Error
+
+1. Network corruption during chunk upload
+2. Client reported wrong file size
+3. Retry full upload from beginning
+
+### S3 Upload Errors
+
+1. Verify AWS credentials: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
+2. Check bucket permissions (PutObject, GetObject, DeleteObject)
+3. Verify region matches bucket location
+4. Check S3 bucket CORS configuration for browser uploads
+
+### Variant Not Showing in PWA
+
+1. Verify variant record exists in `asset_variants` table
+2. Check `cdn_url` is accessible
+3. Verify `variant_type` matches expected values
+4. Check PWA manifest generation includes asset
+
+## Project Cloning and Asset Copying
+
+When a project is cloned, all assets (including variants and reversed videos) are copied to give the cloned project independent files.
+
+### Optimized S3 Copy
+
+The cloning process uses S3's native `CopyObjectCommand` for server-side file copying, which is significantly faster than downloading and re-uploading files.
+
+**Performance Comparison:**
+| Metric | Download/Upload | S3 CopyObject |
+|--------|-----------------|---------------|
+| 100 MB file | ~3,000 ms | ~200 ms |
+| Memory usage | File size in RAM | ~5 MB constant |
+| 569 assets (parallel) | Timeouts likely | ~35 seconds |
+
+### Clone Process for Assets
+
+```
+1. Collect all copy operations:
+   - Primary assets: assets/{oldProjectId}/{uuid}.ext → assets/{newProjectId}/{newUuid}.ext
+   - Non-reversed variants: Same pattern as primary assets
+
+2. Execute parallel S3 copy (10 concurrent)
+
+3. Create asset/variant DB records with new storage paths
+
+4. Build asset ID mapping: oldAssetId → newAssetId
+
+5. Copy reversed videos using asset ID mapping:
+   - assets/{oldAssetId}/reversed.mp4 → assets/{newAssetId}/reversed.mp4
+
+6. Transform ui_schema_json paths in tour_pages
+```
+
+### Why Reversed Videos Need Special Handling
+
+Reversed videos use asset-ID-based paths (`assets/{assetId}/reversed.mp4`), not project-ID-based paths. This requires:
+
+1. **Asset ID Mapping:** Track which old asset ID maps to which new asset ID
+2. **Separate Copy Phase:** Copy reversed videos after creating asset records (so we have the new asset IDs)
+3. **Path Transformation:** Update `reverseVideoUrl` references in `ui_schema_json`
+
+### Error Handling
+
+- **Failed copies:** Fall back to original storage path (cloned project shares asset with source)
+- **Missing reversed videos:** Expected for most assets (only navigation transitions have them)
+- **Transaction rollback:** On DB errors; orphaned S3 files are acceptable (can be cleaned later)
diff --git a/documentation/assets-preloading.md b/documentation/assets-preloading.md
new file mode 100644
index 0000000..78ba99c
--- /dev/null
+++ b/documentation/assets-preloading.md
@@ -0,0 +1,974 @@
+# Assets Preloading Feature - E2E Documentation
+
+## Overview
+
+The Tour Builder Platform implements a sophisticated dual-mode asset preloading system that optimizes user experience in both online and offline scenarios. The system intelligently prefetches assets based on navigation patterns, network conditions, and storage constraints.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Configuration Layer                          │
+│  preload.config.ts │ offline.config.ts                          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                        Hook Layer                                │
+│  usePreloadOrchestrator │ usePageNavigationState │ useNetworkAware│
+│  usePreloadProgress │ usePWAPreload │ useOfflineMode            │
+│  useStorageQuota │ useIconPreload                               │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                       Library Layer                              │
+│  DownloadEventBus │ DownloadManager │ StorageManager            │
+│  OfflineDbManager │ extractPageLinks │ assetCache               │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Service Worker (Serwist)                     │
+│  sw.ts - CacheFirst, NetworkFirst, Range Request Support        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Recent Refactor:** The preloading system was simplified to use a "stream-first" approach:
+- **Online mode:** Preloads current page + outgoing transition videos only (no neighbor preloading)
+- **Offline mode:** Full project assets downloaded via `useOfflineMode.startDownload()`
+- **Video playback:** Streams on-demand, then caches for replay (no bandwidth competition)
+- `useNeighborGraph` was removed (neighbor preloading caused excessive network requests)
+- `usePageSwitch`, `useBackgroundTransition`, and other hooks were consolidated into `usePageNavigationState`
+
+---
+
+## Online Mode (Stream-First)
+
+### How It Works
+
+Online mode uses a **stream-first** approach orchestrated by `usePreloadOrchestrator.ts`:
+- **Current page assets** are preloaded (backgrounds, element images)
+- **Outgoing transition videos** are preloaded for instant playback
+- **Other videos** stream on-demand using presigned URLs (browser handles buffering)
+- **No neighbor page preloading** - eliminated to reduce network contention
+
+### Asset Discovery Flow
+
+1. **Page Change Detection** - Monitors `currentPageId` changes
+2. **Current Page Asset Extraction** - Extracts URLs from:
+   - **Page backgrounds** - `background_image_url`, `background_video_url`, `background_audio_url`
+   - **Element content** - URLs from `ui_schema_json` elements
+3. **Transition Video Extraction** - Gets `transitionVideoUrl` from outgoing page links
+4. **Priority Assignment** - Assigns download priority based on asset type
+
+### Asset URL Extraction Fields
+
+The system extracts URLs from these `content_json` fields (configured in `PRELOAD_CONFIG.assetFields`):
+
+**Direct Fields:**
+`iconUrl`, `imageUrl`, `mediaUrl`, `videoUrl`, `audioUrl`, `transitionVideoUrl`, `backgroundImageUrl`, `reverseVideoUrl`, `carouselPrevIconUrl`, `carouselNextIconUrl`, `src`, `url`, `poster`, `thumbnail`
+
+**Nested Arrays:**
+- `galleryCards[].imageUrl`, `galleryCards[].videoUrl`
+- `carouselSlides[].imageUrl`, `carouselSlides[].videoUrl`
+
+**Page Links:**
+- `pageLink.transition.video_url` (eagerly loaded from backend API)
+
+### Priority Calculation
+
+```
+Priority = basePriority + assetTypeBonus + variantBonus
+
+Current Page Assets:    priority = 1000 + bonuses
+Transition Videos:      priority = 1000 + 150 = 1150 (highest)
+```
+
+**Asset Type Multipliers:**
+| Type | Weight | Notes |
+|------|--------|-------|
+| Transition | 150 | Highest - needed immediately on navigation click |
+| Image | 100 | Background and UI elements |
+| Audio | 50 | Background audio tracks |
+| Video | 30 | Lower priority since they stream |
+
+**Note:** Neighbor page preloading was removed to simplify the system and reduce network contention. Videos stream on-demand using presigned URLs with browser-managed buffering.
+
+**Variant Multipliers:**
+| Variant | Weight |
+|---------|--------|
+| Thumbnail | 50 |
+| Preview | 40 |
+| WebP | 35 |
+| MP4 Low | 20 |
+| MP4 High | 10 |
+| Original | 5 |
+
+### Network-Aware Concurrency
+
+The system adapts download concurrency based on network conditions via `useNetworkAware.ts`:
+
+| Connection | Concurrent Downloads | Strategy |
+|------------|---------------------|----------|
+| 4g / Good | 3 | Aggressive |
+| 3g | 2 | Normal |
+| 2g / Slow | 1 | Conservative |
+| Save-Data | 1 | Minimal |
+
+**Network Thresholds:**
+- Aggressive: 4g OR downlink ≥ 5Mbps
+- Suggest offline: slow-2g OR 2g OR RTT > 500ms OR downlink < 0.5Mbps
+- Low quality: save-data flag OR slow-2g OR downlink < 1Mbps
+
+### Download Process
+
+1. Fetch asset with progress tracking via ReadableStream
+2. Emit progress events via `DownloadEventBus`
+3. Store in Cache API (`tour-builder-assets-v1`) under download URL
+4. **Store in Cache API under storage key** (enables post-refresh lookups)
+5. **Create Blob URL**: `URL.createObjectURL(blob)` for local reference
+6. **Image Decoding**: Call `image.decode()` on the blob URL to eliminate white flash on navigation
+7. **Store Ready URLs**: Map both download URL AND storage key to blob URL in `readyBlobUrlsRef`
+8. Track cached assets in memory Set for quick lookups
+
+**Storage Key Mapping (Key Feature):**
+
+The system maps assets by **canonical storage key** (e.g., `assets/project-123/video.mp4`) in addition to download URLs. This solves the presigned URL mismatch problem where different requests generate different signatures.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────────────┐
+│                               STORAGE KEY MAPPING                                        │
+│                                                                                          │
+│  Storage Key: "assets/project-123/video.mp4"  ← CANONICAL IDENTIFIER (never changes)   │
+│                        │                                                                 │
+│         ┌──────────────┴──────────────┐                                                 │
+│         ▼                              ▼                                                 │
+│  Download URL #1                Download URL #2                                          │
+│  "https://s3...?Sig=ABC"       "https://s3...?Sig=XYZ"                                  │
+│         │                              │                                                 │
+│         ▼                              ▼                                                 │
+│  ┌─────────────────────────────────────────────────────────────────────┐                │
+│  │                     readyBlobUrlsRef Map                             │                │
+│  │  key: storageKey  ────────────►  blob://...                         │                │
+│  │  key: downloadUrl ────────────►  blob://... (same blob URL)         │                │
+│  └─────────────────────────────────────────────────────────────────────┘                │
+│                                                                                          │
+│  Lookup: getReadyBlobUrl(storageKey) → O(1) instant → blob://...                        │
+└─────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+**Why storage key mapping matters:**
+
+| Scenario | Download URL | Storage Key | Lookup Result |
+|----------|-------------|-------------|---------------|
+| Same session | `https://s3...?Sig=ABC` | `assets/vid.mp4` | ✅ Instant via storage key |
+| New presigned URL | `https://s3...?Sig=XYZ` | `assets/vid.mp4` | ✅ Instant via storage key |
+| Page refresh | N/A (in-memory cleared) | `assets/vid.mp4` | ✅ From Cache API by storage key |
+
+**Ready Blob URL Flow:**
+```
+Download → Cache API (URL key) → Cache API (storage key) → Blob URL → Image Decode
+                                                                    ↓
+                                            ┌── readyBlobUrlsRef.set(downloadUrl, blobUrl)
+                                            └── readyBlobUrlsRef.set(storageKey, blobUrl)
+                                            └── readyUrlsVersion++ (triggers re-render)
+                                                                    ↓
+Navigation Click → getReadyBlobUrl(storageKey) → O(1) lookup → Instant display
+```
+
+**Re-render Trigger Mechanism:**
+
+Since `readyBlobUrlsRef` is a ref (not state), updates don't trigger React re-renders. The `readyUrlsVersion` counter solves this:
+
+1. When a blob URL becomes ready, `setReadyUrlsVersion(v => v + 1)` is called
+2. Components using `readyUrlsVersion` in dependency arrays re-render
+3. `resolveUrlWithBlob` callbacks are recreated with fresh lookups
+4. UI switches from direct URLs to cached blob URLs
+
+```typescript
+// In constructor.tsx
+const resolveUrlWithBlob = useCallback(
+  (url) => {
+    const blobUrl = preloadOrchestrator.getReadyBlobUrl(url);
+    if (blobUrl) return blobUrl;
+    return resolveAssetPlaybackUrl(url);
+  },
+  [preloadOrchestrator, preloadOrchestrator.readyUrlsVersion], // Re-render when ready
+);
+```
+
+### Presigned URL Integration
+
+For S3 storage, the preloader fetches presigned URLs before downloading assets for direct S3 access:
+
+```typescript
+// In usePreloadOrchestrator.ts
+// 1. Collect storage paths that need presigning
+const storagePaths = assets
+  .map(a => a.url)
+  .filter(isRelativeStoragePath);
+
+// 2. Batch fetch presigned URLs (auto-batches and caches)
+queuePresignedUrls(storagePaths)
+  .then(() => {
+    // 3. Add assets to queue with resolved URLs
+    assets.forEach(asset => {
+      const presignedUrl = getPresignedUrl(asset.url);
+      const resolvedUrl = presignedUrl || resolveAssetPlaybackUrl(asset.url);
+      addToQueue({ url: resolvedUrl, storageKey: asset.url, ... });
+    });
+  })
+  .catch(() => {
+    // Fallback to proxy URLs
+    addAssetsToQueue();
+  });
+
+// 4. On successful download, mark presigned URLs as verified
+// (enables resolveAssetPlaybackUrl to use presigned URLs)
+if (isPresignedUrl(item.url)) {
+  markPresignedUrlsVerified();
+}
+```
+
+**Key Functions (lib/assetUrl.ts):**
+| Function | Purpose |
+|----------|---------|
+| `queuePresignedUrl()` | Queue single URL for presigning |
+| `queuePresignedUrls()` | Batch queue URLs for presigning |
+| `flushPresignedUrlQueue()` | Fetch queued presigned URLs |
+| `getPresignedUrl()` | Get cached presigned URL (sync) |
+| `resolveAssetPlaybackUrl()` | Resolve URL with presigned cache lookup |
+| `markPresignedUrlFailed()` | Mark presigned URL as failed for specific key |
+| `markPresignedUrlsVerified()` | Mark presigned URLs as verified (enables playback URL resolution) |
+| `isRelativeStoragePath()` | Check if URL is a relative storage path (needs presigning) |
+| `extractStoragePath()` | Extract storage path from full URL (handles S3, CDN, proxy URLs) |
+| `setupPresignedUrlInterceptor()` | Setup Axios interceptor for CORS failure detection |
+| `disablePresignedUrls()` | Globally disable presigned URLs (fallback to proxy) |
+| `arePresignedUrlsDisabled()` | Check if presigned URLs are disabled |
+| `clearPresignedUrlCache()` | Clear all cached presigned URLs |
+
+**Key Functions (usePreloadOrchestrator):**
+| Function | Purpose |
+|----------|---------|
+| `getReadyBlobUrl(key)` | O(1) instant lookup by storage key or resolved URL |
+| `getCachedBlobUrl(key)` | Async lookup from Cache API by storage key or resolved URL |
+| `isUrlPreloaded(key)` | Check if asset is ready for instant display |
+
+**Lookup Priority (in usePageSwitch and useTransitionPlayback):**
+```
+1. getReadyBlobUrl(storageKey)   → instant O(1) (same session)
+2. getCachedBlobUrl(storageKey)  → Cache API (~5ms, post-refresh)
+3. getReadyBlobUrl(resolvedUrl)  → fallback
+4. getCachedBlobUrl(resolvedUrl) → fallback
+5. Network fetch                 → last resort
+```
+
+**Fallback Behavior:**
+- If presigned URL fails (CORS not configured), DownloadManager automatically retries with proxy URL
+- This fallback is built into DownloadManager as single source of truth (no duplicate retry logic)
+- Retry happens immediately with reset retry count
+- Logger tracks presigned URL status changes: `[DownloadManager] Presigned URL failed, retrying with proxy`
+
+### Key Files
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `usePreloadOrchestrator.ts` | `frontend/src/hooks/` | Main orchestrator with ready blob URL management |
+| `usePageSwitch.ts` | `frontend/src/hooks/` | Page navigation using preloaded blob URLs |
+| `useNeighborGraph.ts` | `frontend/src/hooks/` | BFS navigation graph, extracts page backgrounds + element assets |
+| `useNetworkAware.ts` | `frontend/src/hooks/` | Network condition monitoring |
+| `useIconPreload.ts` | `frontend/src/hooks/` | Constructor icon preloading to prevent flash |
+| `extractPageLinks.ts` | `frontend/src/lib/` | Extract navigation targets and preload elements from pages |
+| `preload.config.ts` | `frontend/src/config/` | Queue and priority settings |
+| `assetUrl.ts` | `frontend/src/lib/` | URL resolution with presigned URL cache |
+
+### Key Methods
+
+| Method | Hook | Purpose |
+|--------|------|---------|
+| `getReadyBlobUrl(key)` | usePreloadOrchestrator | O(1) instant lookup by storage key or resolved URL |
+| `getCachedBlobUrl(key)` | usePreloadOrchestrator | Async lookup from Cache API by storage key or URL |
+| `isUrlPreloaded(key)` | usePreloadOrchestrator | Check if asset is ready for instant display |
+| `preloadAsset(url)` | usePreloadOrchestrator | Manually trigger preload for a specific URL |
+| `clearQueue()` | usePreloadOrchestrator | Clear the preload queue |
+| `switchToPage(page, onSwitched?)` | usePageSwitch | Navigate with preloaded assets (resolves by storage key first) |
+| `setBackgroundsDirectly(img, vid, aud)` | usePageSwitch | Set backgrounds without transition overlay (initial load) |
+| `markBackgroundReady()` | usePageSwitch | Mark new background as ready (call from Image onLoad) |
+| `clearPreviousBackground()` | usePageSwitch | Clear overlay after transition completes |
+
+---
+
+## Offline Mode
+
+### Storage Strategy
+
+The system uses a hybrid storage approach for optimal performance:
+
+```
+Assets < 5MB  →  Cache API (tour-builder-assets-v1)
+Assets ≥ 5MB  →  IndexedDB (TourBuilderOffline)
+```
+
+**Why Hybrid:**
+- Cache API has better browser support but size limitations
+- IndexedDB provides reliable large file storage
+- `StorageManager` abstracts both for transparent access
+
+### IndexedDB Schema (Dexie.js)
+
+**Database:** `TourBuilderOffline` (version 1)
+
+**Tables and Indexes:**
+```javascript
+{
+  assets: 'id, projectId, url, variantType, assetType, downloadedAt',
+  projects: 'id, slug, status, lastSyncedAt',
+  downloadQueue: 'id, projectId, status, priority, addedAt'
+}
+```
+
+**TypeScript Interfaces:**
+
+```typescript
+// OfflineAsset - Large files stored in IndexedDB
+interface OfflineAsset {
+  id: string;
+  projectId: string;
+  url: string;
+  filename: string;
+  variantType: AssetVariantType;
+  assetType: AssetType;
+  mimeType: string;
+  sizeBytes: number;
+  blob: Blob;
+  downloadedAt: number;
+}
+
+// OfflineProject - Project offline status
+interface OfflineProject {
+  id: string;
+  slug: string;
+  name: string;
+  status: ProjectOfflineStatus;
+  totalAssets: number;
+  downloadedAssets: number;
+  totalSizeBytes: number;
+  downloadedSizeBytes: number;
+  lastSyncedAt?: number;
+  version?: string;
+}
+
+// DownloadQueueItem - Persistent download queue
+interface DownloadQueueItem {
+  id: string;
+  projectId: string;
+  assetId: string;
+  url: string;
+  filename: string;
+  status: PreloadJobStatus;
+  priority: number;
+  retryCount: number;
+  bytesLoaded: number;
+  totalBytes: number;
+  addedAt: number;
+  lastAttemptAt?: number;
+  error?: string;
+}
+```
+
+### Asset Storage Flow
+
+```
+storeAsset(blob, metadata)
+        │
+        ├── Size < 5MB?
+        │       │
+        │       YES → Create Response with headers
+        │             → Store in Cache API
+        │
+        └── Size ≥ 5MB?
+                │
+                YES → Create OfflineAsset object
+                      → Store in IndexedDB
+```
+
+### Asset Retrieval Flow
+
+```
+getAsset(url)  [StorageManager.getAsset()]
+    │
+    ├── Check IndexedDB first (large files)
+    │       │
+    │       └── Found? → Return blob
+    │
+    └── Check Cache API (small files)
+            │
+            └── Found? → Return response blob
+```
+
+### Service Worker (Serwist)
+
+Located at `frontend/src/sw.ts`, handles offline caching:
+
+| Resource Type | Strategy | Cache Name |
+|--------------|----------|------------|
+| Static Assets (images, fonts, css, js) | CacheFirst | `tour-builder-assets-v1` |
+| Videos | CacheFirst + Range | `tour-builder-assets-v1` |
+| API Responses | NetworkFirst | `api-cache` |
+| Pages | NetworkFirst | (default) |
+
+**Unified Cache Keys (cacheKeyWillBeUsed Plugin):**
+
+The Service Worker normalizes all asset URLs to storage keys using `cacheKeyWillBeUsed` plugin. This ensures preload (DownloadManager) and browser loads (SW interception) use the same cache keys:
+
+```typescript
+// SW plugin for static assets handler
+cacheKeyWillBeUsed: async ({ request, mode }) => {
+  const storagePath = extractStoragePathFromUrl(request.url);
+  if (storagePath) {
+    return new Request(storagePath);
+  }
+  return request;
+}
+```
+
+**Why this matters:**
+| Before | After |
+|--------|-------|
+| Preload stores: `assets/project/file.jpg` | Same |
+| Browser load stores: `https://s3.../file.jpg?X-Amz-Signature=abc` | `assets/project/file.jpg` |
+| New session with new presigned URL → cache MISS | cache HIT (same key) |
+
+**Range Request Support for Videos:**
+- Handles byte-range requests for video seeking
+- Extracts range from cached response
+- Returns partial content (HTTP 206)
+
+### Asset Discovery (Unified Frontend)
+
+Located at `frontend/src/lib/assetCache/`, provides unified asset discovery for both online preload and offline download:
+
+```typescript
+// Discover all assets for a project (used by offline mode)
+discoverProjectAssets(pages, pageLinks, elements): AssetToCache[]
+
+// Get prioritized assets for preloading (used by online preload)
+getPrioritizedAssets(currentPageId, pages, pageLinks, elements, neighbors): AssetToCache[]
+```
+
+**Asset Discovery Sources:**
+- Page backgrounds: `background_image_url`, `background_video_url`, `background_audio_url`
+- Element content_json: All URL fields from `PRELOAD_CONFIG.assetFields.all`
+- Transition videos: `transition.video_url` from page links
+- Nested arrays: `galleryCards[]`, `carouselSlides[]`
+
+**AssetToCache Structure:**
+```typescript
+interface AssetToCache {
+  storageKey: string;      // Canonical key for caching
+  originalUrl: string;     // Original URL from data
+  assetType: AssetType;    // 'image' | 'video' | 'audio' | 'transition' | 'other'
+  pageId: string;          // Page the asset belongs to
+  priority: number;        // Download priority (higher = first)
+}
+```
+
+### Navigation Data in ui_schema_json
+
+Navigation targets and transition videos are stored directly in `tour_pages.ui_schema_json`:
+
+```typescript
+// Element with navigation and transition
+{
+  type: "navigation_next",
+  targetPageSlug: "gallery",           // Slug-based navigation
+  transitionVideoUrl: "assets/.../transition.mp4",  // Inline transition
+  transitionDurationSec: 1.5,
+}
+```
+
+The preload system extracts navigation targets from elements to build the neighbor graph, and transition video URLs are used directly for preloading.
+
+### Key Files
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `StorageManager.ts` | `frontend/src/lib/offline/` | Cache API + IndexedDB abstraction |
+| `DownloadManager.ts` | `frontend/src/lib/offline/` | Download queue with auto proxy fallback |
+| `OfflineDbManager.ts` | `frontend/src/lib/offlineDb/` | Dexie.js IndexedDB manager |
+| `schema.ts` | `frontend/src/lib/offlineDb/` | Dexie.js schema definition |
+| `AssetCacheService.ts` | `frontend/src/lib/assetCache/` | Unified asset caching service |
+| `assetDiscovery.ts` | `frontend/src/lib/assetCache/` | Shared asset extraction logic |
+| `offline.config.ts` | `frontend/src/config/` | Offline settings |
+| `sw.ts` | `frontend/src/` | Serwist service worker |
+| `useNeighborGraph.ts` | `frontend/src/hooks/` | Builds navigation graph from elements |
+
+---
+
+## Progress Tracking
+
+### Event System
+
+The `DownloadEventBus` singleton emits events consumed by `usePreloadProgress`:
+
+```
+DownloadEventBus
+    │
+    ├── preloadStart    { jobId, assetId, url }
+    ├── preloadProgress { jobId, progress, bytesLoaded, totalBytes }
+    ├── preloadComplete { jobId, assetId }
+    └── preloadError    { jobId, assetId, error }
+            │
+            ▼
+    usePreloadProgress Hook
+            │
+            ├── Maintains jobs[] array
+            ├── Calculates totalProgress
+            ├── Auto-removes completed (3s)
+            └── Auto-removes errors (10s)
+            │
+            ▼
+    UI Components
+            │
+            ├── OfflineToggle
+            ├── OfflineStatusIndicator
+            └── DownloadProgressPanel
+```
+
+---
+
+## Configuration Reference
+
+### preload.config.ts
+
+```typescript
+export const PRELOAD_CONFIG = {
+  // Queue settings
+  maxConcurrentDownloads: 3,
+  maxRetries: 3,
+  retryDelayMs: 1000,
+
+  // Size thresholds
+  largeFileThreshold: 5 * 1024 * 1024, // 5MB -> use IndexedDB
+  videoChunkSize: 5 * 1024 * 1024,     // 5MB chunks
+  initialVideoBufferSeconds: 5,
+
+  // Priority weights
+  priority: {
+    currentPage: 1000,
+    neighborBase: 500,
+    assetType: {
+      transition: 150, // Highest - needed immediately on navigation click
+      image: 100,
+      audio: 50,
+      video: 30,
+    },
+    variant: {
+      thumbnail: 50,
+      preview: 40,
+      webp: 35,
+      mp4_low: 20,
+      mp4_high: 10,
+      original: 5,
+    },
+    linkCountMultiplier: 10,
+    maxLinkBonus: 50,
+  },
+
+  // Storage thresholds
+  storage: {
+    warningPercent: 80,
+    criticalPercent: 95,
+    minFreeBuffer: 50 * 1024 * 1024, // 50MB
+  },
+
+  // Auto-cleanup timeouts
+  autoRemove: {
+    completedMs: 3000,
+    errorMs: 10000,
+  },
+
+  // Neighbor graph traversal
+  neighborGraph: {
+    maxDepth: 1,           // Only preload immediate neighbors (reduced from 2)
+    constructorMaxDepth: 1, // Same as maxDepth for constructor
+  },
+
+  // Asset URL field names for extraction
+  assetFields: {
+    all: [
+      'iconUrl', 'imageUrl', 'mediaUrl', 'videoUrl', 'audioUrl',
+      'transitionVideoUrl', 'backgroundImageUrl', 'reverseVideoUrl',
+      'carouselPrevIconUrl', 'carouselNextIconUrl', 'src', 'url',
+      'poster', 'thumbnail'
+    ],
+    images: [
+      'iconUrl', 'imageUrl', 'backgroundImageUrl',
+      'carouselPrevIconUrl', 'carouselNextIconUrl', 'src'
+    ],
+    nested: ['galleryCards', 'carouselSlides'],
+    nestedUrlFields: ['imageUrl', 'videoUrl'],
+  },
+};
+```
+
+### offline.config.ts
+
+```typescript
+export const OFFLINE_CONFIG = {
+  // IndexedDB
+  dbName: 'TourBuilderOffline',
+  dbVersion: 1,
+
+  // Cache names (for Cache API)
+  cacheNames: {
+    static: 'tour-builder-static-v1',
+    dynamic: 'tour-builder-dynamic-v1',
+    assets: 'tour-builder-assets-v1',
+  },
+
+  // Events (EventEmitter event names)
+  events: {
+    preloadStart: 'asset-preload-start',
+    preloadProgress: 'asset-preload-progress',
+    preloadComplete: 'asset-preload-complete',
+    preloadError: 'asset-preload-error',
+    projectDownloadProgress: 'project-download-progress',
+    projectDownloadComplete: 'project-download-complete',
+    queueUpdate: 'queue-update',
+  },
+
+  // Service worker settings
+  serviceWorker: {
+    scope: '/',
+    updateInterval: 60 * 60 * 1000, // 1 hour
+  },
+
+  // Storage settings
+  storage: {
+    cacheApiMaxSize: 5 * 1024 * 1024,  // 5MB
+    indexedDbMinSize: 5 * 1024 * 1024, // 5MB
+  },
+
+  // Retry settings
+  retry: {
+    maxRetries: 3,
+    backoffMs: 1000,
+    maxBackoffMs: 30000,
+  },
+};
+```
+
+---
+
+## Integration Examples
+
+### Runtime Mode (Tour Playback)
+
+```typescript
+// frontend/src/pages/runtime.tsx
+const preloadOrchestrator = usePreloadOrchestrator({
+  pages,
+  pageLinks,  // Includes transition.video_url from API
+  elements,
+  currentPageId: selectedPageId,
+  pageHistory,
+  enabled: !isLoading && !error,
+});
+
+// Pass getCachedBlobUrl to reverse playback hook
+const { startReverse, stopReverse } = useReversePlayback({
+  videoRef: overlayVideoRef,
+  onComplete: finishOverlayTransition,
+  preloadedUrls: preloadOrchestrator.preloadedUrls,
+  videoUrl: overlayTransition?.videoUrl,
+  getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+});
+```
+
+### RuntimePresentation Mode (Embedded/Standalone)
+
+```typescript
+// frontend/src/components/RuntimePresentation.tsx
+
+// 1. Filter pages by environment (dev, stage, or production)
+const filteredPages = pages.filter(p => p.environment === environment);
+
+// 2. Extract navigation targets and preload elements from ui_schema_json
+const { pageLinks, preloadElements } = extractPageLinksAndElements(filteredPages);
+
+// 3. Initialize preload orchestrator
+const preloadOrchestrator = usePreloadOrchestrator({
+  pages: filteredPages,
+  pageLinks,           // Navigation links with transition videos
+  elements: preloadElements,  // All preloadable elements
+  currentPageId: selectedPageId,
+  pageHistory,
+  enabled: !isLoading && !error,
+});
+
+// 4. Initialize page switch with preload cache
+const pageSwitch = usePageSwitch({
+  preloadCache: preloadOrchestrator
+    ? {
+        getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,  // O(1) instant lookup
+        getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+        preloadedUrls: preloadOrchestrator.preloadedUrls,
+      }
+    : undefined,
+});
+
+// 5. Navigate using preloaded assets for instant display
+const handleNavigation = (targetPage, link) => {
+  pageSwitch.switchToPage(targetPage, link);  // Uses ready blob URLs
+};
+
+// OfflineToggle for user-initiated downloads
+<OfflineToggle
+  projectId={project?.id || null}
+  projectSlug={projectSlug}
+  projectName={project?.name}
+  pages={filteredPages}  // Required: pages for asset discovery
+  showLabel={false}
+  size='small'
+/>
+```
+
+**Environment Filtering:**
+Pages are filtered by environment (`dev`, `stage`, `production`) before preloading. This ensures:
+- Constructor always preloads `dev` environment pages
+- Stage preview preloads `stage` environment pages
+- Production runtime preloads `production` environment pages
+
+### Constructor Mode (Editing)
+
+```typescript
+// frontend/src/pages/constructor.tsx
+
+// Constructor always works with 'dev' environment pages
+const { pageLinks, preloadElements } = extractPageLinksAndElements(pages);
+
+const preloadOrchestrator = usePreloadOrchestrator({
+  pages,
+  pageLinks,
+  elements: preloadElements,
+  currentPageId: activePageId,
+  enabled: !isLoading && !!activePageId,
+  // maxNeighborDepth defaults to 1 (same as runtime)
+});
+
+// Page switch for preview navigation
+const pageSwitch = usePageSwitch({
+  preloadCache: preloadOrchestrator
+    ? {
+        getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,
+        getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+        preloadedUrls: preloadOrchestrator.preloadedUrls,
+      }
+    : undefined,
+});
+```
+
+### Offline Mode Hook
+
+```typescript
+// frontend/src/components/Offline/OfflineToggle.tsx
+const {
+  isOfflineCapable,
+  isDownloaded,
+  isDownloading,
+  status,
+  progress,
+  startDownload,
+  pauseDownload,
+  resumeDownload,
+  cancelDownload,
+  deleteOfflineData,
+  estimatedSize,
+  formatSize,
+} = useOfflineMode({
+  projectId,
+  projectSlug,
+  projectName,
+  pages,  // Required: pages data for frontend asset discovery
+});
+```
+
+### Video Reverse Playback
+
+```typescript
+// frontend/src/hooks/useReversePlayback.ts
+// Tries native playbackRate = -1 first (Chrome 141+, Safari 16+)
+// Falls back to frame-stepping with cached blob URL for better seeking
+
+const cachedUrl = await getCachedBlobUrl(videoUrl);
+if (cachedUrl) {
+  video.src = cachedUrl;  // Better seeking with local blob
+  video.load();
+}
+```
+
+---
+
+## Complete Data Flow Example
+
+**Scenario: User navigates from Page A to Page B**
+
+```
+1. Page Change Detection
+   └── currentPageId: "pageA" → "pageB"
+
+2. Neighbor Discovery (BFS via useNeighborGraph, depth=1)
+   └── pageB neighbors: [pageC (dist=1)]  // Only immediate neighbors
+
+3. Asset Extraction (via useNeighborGraph.getAssetsForPages)
+   ├── pageB backgrounds (from page object)
+   │   ├── background_image_url → [bg.jpg]
+   │   ├── background_video_url → [bg-video.mp4] (if exists)
+   │   └── background_audio_url → [bg-audio.mp3] (if exists)
+   ├── pageB elements → [img1.webp, video1.mp4]
+   ├── pageC backgrounds → [pageC-bg.jpg]
+   ├── pageC elements → [img2.webp]
+   └── pageLink B→C transition.video_url → [trans.mp4]
+
+4. Priority Assignment
+   ├── img1.webp   → 1000 + 100 + 35 = 1135
+   ├── bg.jpg      → 1000 + 100 + 5  = 1105
+   ├── video1.mp4  → 1000 + 30 + 20  = 1050
+   ├── trans.mp4   → 500 + 150 + 20  = 670   // Transition has highest type bonus
+   └── img2.webp   → 500 + 100 + 35  = 635
+
+5. Network Check (useNetworkAware)
+   └── 4g detected → concurrency = 3
+
+6. Download Queue (sorted by priority)
+   [img1.webp, bg.jpg, video1.mp4, trans.mp4, img2.webp]
+
+7. Parallel Download (3 concurrent)
+   ├── Download blob via presigned URL
+   ├── Store in Cache API
+   ├── Create blob URL
+   ├── Decode (images only)
+   └── Store in readyBlobUrlsRef Map
+
+8. Progress Events
+   └── DownloadEventBus → usePreloadProgress → UI
+
+9. Navigation Click (instant)
+   └── getReadyBlobUrl(url) → O(1) Map lookup → Pre-decoded blob URL
+   └── Set as background → No delay, no flash
+```
+
+---
+
+## Storage Quota Management
+
+The system monitors storage usage via `navigator.storage.estimate()`:
+
+```typescript
+const { usage, quota } = await navigator.storage.estimate();
+const percentUsed = (usage / quota) * 100;
+const available = quota - usage - PRELOAD_CONFIG.storage.minFreeBuffer;
+
+if (percentUsed > 95) {
+  // Critical: stop preloading
+} else if (percentUsed > 80) {
+  // Warning: reduce preload depth
+}
+```
+
+The `useStorageQuota` hook provides reactive storage monitoring:
+
+```typescript
+const { canStore, isWarning, isCritical } = useStorageQuota();
+
+// Used in OfflineToggle to warn users before download
+if (isCritical) {
+  alert('Storage space is critically low.');
+  return;
+}
+```
+
+---
+
+## Troubleshooting
+
+### Assets Not Preloading
+1. Check network status in DevTools
+2. Verify `enabled` prop is `true`
+3. Check Console for preload errors (look for `[PRELOAD]` prefix)
+4. Verify Cache API storage quota
+5. Check that `pageLinks` include `transition.video_url`
+
+### Offline Mode Not Working
+1. Ensure Service Worker is registered
+2. Check IndexedDB for stored assets (`TourBuilderOffline` database)
+3. Verify `pages` prop is passed to `OfflineToggle` / `useOfflineMode`
+4. Check for CORS issues on asset URLs
+5. Verify `OfflineToggle` component is rendered
+
+### Video Seeking Issues Offline
+1. Verify video is in cache with correct headers
+2. Check Service Worker handles range requests (HTTP 206)
+3. Verify `getCachedBlobUrl` returns blob URL
+4. Try clearing cache and re-downloading
+
+### Reverse Playback Not Working
+1. Check if `getCachedBlobUrl` is passed to `useReversePlayback`
+2. Verify transition video URL is preloaded
+3. Check Console for `[REVERSE]` logs
+4. Verify `preloadedUrls` Set contains the video URL
+
+---
+
+## Performance Considerations
+
+1. **Storage Key Mapping**: Assets mapped by canonical storage key (e.g., `assets/vid.mp4`) enabling cache hits regardless of presigned URL changes
+2. **Ready Blob URLs**: Use `getReadyBlobUrl(storageKey)` for O(1) instant lookup of pre-decoded blob URLs
+3. **Post-Refresh Cache**: Assets stored in Cache API under storage key survive page refresh
+4. **Image Decoding**: Blob URLs are pre-decoded to prevent white flash on navigation
+5. **Neighbor Depth**: `maxNeighborDepth=1` for both editing and playback (reduced to prevent too many requests)
+6. **Transition Priority**: Transitions have highest priority (150) - needed immediately on navigation click
+7. **Large Videos**: Stored in IndexedDB (≥5MB) for reliable playback
+8. **Network Adaptation**: Reduces concurrency on slow connections
+9. **Memory Management**: Auto-cleans completed jobs from progress tracking; blob URLs revoked on unmount
+10. **Environment Filtering**: Pages filtered by environment before preloading to avoid loading wrong content
+11. **Service Worker Cache**: Same cache name (`tour-builder-assets-v1`) used by preloading and SW
+12. **Blob URL Rendering**: Use native `<img>` for blob URLs instead of Next.js Image to prevent re-fetching
+
+---
+
+## Blob URL Rendering Strategy
+
+When displaying preloaded blob URLs, use native `<img>` tags instead of Next.js `<Image>`:
+
+```tsx
+// Background image with conditional rendering
+{backgroundImageUrl.startsWith('blob:') ? (
+  <img
+    src={backgroundImageUrl}
+    alt=""
+    className="absolute inset-0 w-full h-full object-cover"
+    onLoad={() => markBackgroundReady()}
+  />
+) : (
+  <NextImage
+    src={backgroundImageUrl}
+    fill
+    sizes="100vw"
+    className="object-cover"
+    onLoad={() => markBackgroundReady()}
+  />
+)}
+```
+
+**Why this matters:**
+- Next.js `<Image>` re-fetches `src` on every component re-render, even with `unoptimized`
+- Pages with frequent state updates (e.g., 100ms animation timers) cause thousands of requests
+- Blob URLs are already in-memory and don't benefit from Next.js optimization
+- Native `<img>` with blob URLs is cached by browser and doesn't re-fetch
+
+**Where to apply:**
+- Background images in RuntimePresentation and Constructor
+- Element icons (tooltip, description, gallery, carousel)
+- Any image element receiving blob URLs from `getReadyBlobUrl()`
diff --git a/documentation/audio-playback.md b/documentation/audio-playback.md
new file mode 100644
index 0000000..136cb68
--- /dev/null
+++ b/documentation/audio-playback.md
@@ -0,0 +1,499 @@
+# Audio Playback Feature - E2E Documentation
+
+## Overview
+
+The Tour Builder Platform implements a comprehensive audio playback system supporting background audio on pages, element-triggered audio effects (hover/click sounds), and media player elements. Key features:
+
+- **User Interaction Unlock**: All audio waits for first user click/tap before playing (consistent across all browsers)
+- **Sound Effects Layering**: Hover/click effects play over background audio (no interruption)
+- **Media Player Ducking**: AudioPlayer and VideoPlayer elements pause background audio when playing
+- **Constructor Modes**: Edit mode silences audio; Interact mode enables full audio playback
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Audio Types                                 │
+│  Background Audio    │    Element Audio Effects                  │
+│  (page-level)        │    (hover/click sounds)                   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Playback Hooks                               │
+│  useBackgroundAudioPlayback │ useAudioEffects │ useAudioEventMgr│
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Controller Layer                             │
+│  backgroundAudioController (singleton for audio ducking)         │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Rendering                                    │
+│  CanvasBackground │ UiElements (hover/click audio)              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Audio Types
+
+### 1. Background Audio
+
+Page-level ambient audio that plays behind all content with configurable playback settings.
+
+```tsx
+// Using useBackgroundAudioPlayback hook for controlled playback
+const { audioRef } = useBackgroundAudioPlayback({
+  audioUrl: page.background_audio_url,
+  autoplay: page.background_audio_autoplay ?? true,
+  loop: page.background_audio_loop ?? true,
+  startTime: page.background_audio_start_time ?? null,
+  endTime: page.background_audio_end_time ?? null,
+});
+
+<audio ref={audioRef} src={audioUrl} preload="auto" hidden />
+```
+
+**Configurable Properties (stored in `tour_pages`):**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `background_audio_autoplay` | boolean | true | Start playback automatically |
+| `background_audio_loop` | boolean | true | Loop continuously |
+| `background_audio_start_time` | DECIMAL(10,1) \| null | null | Start playback at this time (seconds) |
+| `background_audio_end_time` | DECIMAL(10,1) \| null | null | Stop/loop at this time (seconds) |
+
+**DECIMAL Parsing (Critical):** Sequelize DECIMAL fields return strings from the database (e.g., `"2.5"` not `2.5`). In runtime code, these must be parsed with `parseFloat(String(value))` before passing to the hook.
+
+**Note:** When `background_audio_end_time` is set, looping is handled via JavaScript (`timeupdate` event) to properly seek back to `startTime`.
+
+### 2. Element Audio Effects
+
+Interactive audio triggered by user hover and click on UI elements.
+
+```tsx
+// Using useAudioEffects hook
+const { playClickAudio, stopAll } = useAudioEffects({
+  hoverAudioUrl: element.hoverAudioUrl,
+  clickAudioUrl: element.clickAudioUrl,
+  volume: element.audioVolume ?? 1,
+  isHovered,
+  isActive,
+  resolveUrl: preloadOrchestrator.getReadyBlobUrl,
+});
+```
+
+**Configurable Properties (stored in element's `ui_schema_json`):**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `hoverAudioUrl` | string | Audio to play on mouse hover |
+| `clickAudioUrl` | string | Audio to play on click/tap |
+| `audioVolume` | number (0-1) | Volume level (iOS ignores this) |
+
+---
+
+## User Interaction Unlock
+
+All audio waits for first user interaction (click/tap) before playing. This ensures consistent behavior across all browsers (Safari, Chrome, Firefox).
+
+### backgroundAudioController
+
+Module-level singleton that manages audio unlock and ducking:
+
+```typescript
+// frontend/src/lib/backgroundAudioController.ts
+
+class BackgroundAudioController {
+  private audioElement: HTMLAudioElement | null = null;
+  private waitingForInteraction = false;
+  private hasUserInteracted = false;
+
+  // Register background audio element
+  register(audio: HTMLAudioElement | null): void;
+
+  // Mark audio as waiting for interaction
+  setWaitingForInteraction(waiting: boolean): void;
+
+  // Called on first user click/tap - unlocks all audio
+  notifyUserInteraction(): void;
+
+  // Check if audio is unlocked
+  hasInteracted(): boolean;
+
+  // Ducking methods for media players
+  notifyForegroundStart(): void;
+  notifyForegroundEnd(): void;
+}
+```
+
+### Unlock Flow
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  1. Page loads                                                │
+│     └── backgroundAudioController.setWaitingForInteraction() │
+│     └── All audio is silent                                  │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  2. User clicks/taps anywhere on canvas                       │
+│     └── handleCanvasInteraction() triggered                  │
+│     └── backgroundAudioController.notifyUserInteraction()    │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  3. Audio unlocked                                            │
+│     └── Background audio starts playing                      │
+│     └── Hover/click effects now work                         │
+│     └── hasInteracted() returns true                         │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Audio Layering & Ducking
+
+Different audio types have different behaviors:
+
+| Audio Type | Background Audio Behavior |
+|------------|---------------------------|
+| **Hover/click effects** | Layers over (plays simultaneously) |
+| **AudioPlayer element** | Pauses background (ducking) |
+| **VideoPlayer element** | Pauses background (ducking) |
+
+### Sound Effects (No Ducking)
+
+Hover and click effects play over background audio without interruption:
+
+```typescript
+// useAudioEffects.ts - no ducking calls
+if (backgroundAudioController.hasInteracted()) {
+  audio.play().catch(() => undefined);
+}
+```
+
+### Media Players (With Ducking)
+
+AudioPlayer and VideoPlayer elements pause background audio:
+
+```typescript
+// AudioPlayerElement.tsx / VideoPlayerElement.tsx
+useEffect(() => {
+  const audio = audioRef.current;
+  if (!audio) return;
+
+  const handlePlay = () => backgroundAudioController.notifyForegroundStart();
+  const handlePause = () => backgroundAudioController.notifyForegroundEnd();
+  const handleEnded = () => backgroundAudioController.notifyForegroundEnd();
+
+  audio.addEventListener('play', handlePlay);
+  audio.addEventListener('pause', handlePause);
+  audio.addEventListener('ended', handleEnded);
+
+  return () => { /* cleanup */ };
+}, []);
+```
+
+### Reference Counting
+
+The controller uses reference counting for multiple media players:
+
+```typescript
+notifyForegroundStart(); // count = 1, background pauses
+notifyForegroundStart(); // count = 2, still paused
+notifyForegroundEnd();   // count = 1, still paused
+notifyForegroundEnd();   // count = 0, background resumes
+```
+
+---
+
+## Browser Autoplay Policy
+
+All major browsers restrict audio autoplay. Our implementation handles this uniformly.
+
+### Browser Policies
+
+| Browser | Policy |
+|---------|--------|
+| **Safari** | Strictest - blocks ALL audio until user interaction |
+| **Chrome** | Blocks until user interaction or high Media Engagement Index |
+| **Firefox** | Blocks by default, user-configurable |
+
+### Our Strategy: Always Wait for Interaction
+
+Instead of trying autoplay and handling failures, we consistently wait for user interaction:
+
+```typescript
+// useBackgroundAudioPlayback.ts
+if (!shouldBlockAutoplay) {
+  // Always wait for user interaction before playing
+  backgroundAudioController.setWaitingForInteraction(true);
+}
+
+// RuntimePresentation.tsx & constructor.tsx
+const handleCanvasInteraction = useCallback(() => {
+  backgroundAudioController.notifyUserInteraction();
+}, []);
+
+<div onClick={handleCanvasInteraction} onTouchEnd={handleCanvasInteraction}>
+```
+
+**Why `onTouchEnd` not `onTouchStart`?** iOS Safari only unlocks audio when finger is LIFTED from screen.
+
+### Session-Scoped Play Once
+
+When `loop=false`, audio only plays once per browser session:
+
+```typescript
+// Module-level Set (cleared on browser refresh)
+const playedAudios = new Set<string>();
+
+// In useBackgroundAudioPlayback
+if (!loop && playedAudios.has(audioStoragePath)) {
+  // Skip autoplay - already played this session
+  return { shouldBlockAutoplay: true };
+}
+
+// After audio plays
+audioElement.onended = () => {
+  playedAudios.add(audioStoragePath);
+};
+```
+
+---
+
+## Constructor Mode
+
+### Edit vs Interact Mode
+
+| Mode | Audio Behavior |
+|------|---------------|
+| **Edit Mode** | All audio silenced (`pauseAudio={true}`) |
+| **Interact Mode** | Full audio playback (after user interaction) |
+
+The constructor passes `pauseAudio={isConstructorEditMode}` to CanvasBackground and only triggers `handleCanvasInteraction` when NOT in edit mode.
+
+### Audio Settings Editor
+
+The Constructor provides UI controls for background audio settings via `BackgroundSettingsEditor`:
+
+```tsx
+// frontend/src/components/Constructor/BackgroundSettingsEditor.tsx
+
+// When type='audio', shows playback settings
+<BackgroundSettingsEditor
+  type="audio"
+  value={backgroundAudioUrl}
+  options={audioAssetOptions}
+  onChange={setBackgroundAudioUrl}
+  audioAutoplay={pageBackground.audioSettings.autoplay}
+  audioLoop={pageBackground.audioSettings.loop}
+  audioStartTime={pageBackground.audioSettings.startTime}
+  audioEndTime={pageBackground.audioSettings.endTime}
+  onAudioSettingsChange={setBackgroundAudioSettings}
+/>
+```
+
+### Settings UI
+
+| Setting | Control | Description |
+|---------|---------|-------------|
+| Autoplay | Checkbox | Start audio automatically on page load |
+| Loop | Checkbox | Continuously loop audio |
+| Start Time | Number input | Begin playback at specific time (seconds) |
+| End Time | Number input | Stop/loop at specific time (seconds) |
+
+---
+
+## Runtime Mode (Presentations)
+
+### RuntimePresentation Component
+
+Passes audio settings to CanvasBackground for playback:
+
+```tsx
+// frontend/src/components/RuntimePresentation.tsx
+
+// Extract audio URL from navigation state
+const backgroundAudioUrl = navCurrentBgAudioUrl;
+
+// Extract settings from selected page
+const audioAutoplay = selectedPage?.background_audio_autoplay ?? true;
+const audioLoop = selectedPage?.background_audio_loop ?? true;
+const audioStartTime = selectedPage?.background_audio_start_time != null
+  ? parseFloat(String(selectedPage.background_audio_start_time))
+  : null;
+const audioEndTime = selectedPage?.background_audio_end_time != null
+  ? parseFloat(String(selectedPage.background_audio_end_time))
+  : null;
+
+// Pass to CanvasBackground
+<CanvasBackground
+  backgroundAudioUrl={backgroundAudioUrl}
+  audioAutoplay={audioAutoplay}
+  audioLoop={audioLoop}
+  audioStartTime={audioStartTime}
+  audioEndTime={audioEndTime}
+  audioStoragePath={selectedPage?.background_audio_url}
+/>
+```
+
+### CanvasBackground Audio Integration
+
+```tsx
+// frontend/src/components/Constructor/CanvasBackground.tsx
+
+const { audioRef } = useBackgroundAudioPlayback({
+  audioUrl: backgroundAudioUrl,
+  audioStoragePath,
+  autoplay: audioAutoplay,
+  loop: audioLoop,
+  startTime: audioStartTime,
+  endTime: audioEndTime,
+});
+
+// Register for audio ducking
+useEffect(() => {
+  backgroundAudioController.register(audioRef.current);
+  return () => backgroundAudioController.register(null);
+}, [audioRef.current]);
+
+// Render hidden audio element
+{backgroundAudioUrl && (
+  <audio ref={audioRef} src={backgroundAudioUrl} preload="auto" hidden />
+)}
+```
+
+---
+
+## Hooks Reference
+
+### useBackgroundAudioPlayback
+
+Manages background audio playback with start/end time control and ducking integration.
+
+```typescript
+interface UseBackgroundAudioPlaybackOptions {
+  audioUrl?: string;              // Audio URL (may be blob URL)
+  audioStoragePath?: string;      // Original storage path for play-once tracking
+  autoplay?: boolean;             // Default: true
+  loop?: boolean;                 // Default: true
+  startTime?: number | null;      // Start at time (seconds)
+  endTime?: number | null;        // Stop/loop at time (seconds)
+  paused?: boolean;               // External pause control
+}
+
+interface UseBackgroundAudioPlaybackResult {
+  audioRef: RefObject<HTMLAudioElement | null>;
+  shouldBlockAutoplay: boolean;   // True if already played this session
+}
+```
+
+**Location:** `frontend/src/hooks/useBackgroundAudioPlayback.ts` (~220 LOC)
+
+### useAudioEventManager
+
+Declarative event listener management for audio elements.
+
+```typescript
+interface UseAudioEventManagerOptions {
+  audioRef: RefObject<HTMLAudioElement | null>;
+  enabled?: boolean;
+  handlers: {
+    onLoadedMetadata?: (event: Event) => void;
+    onTimeUpdate?: (event: Event) => void;
+    onEnded?: (event: Event) => void;
+    onError?: (event: Event) => void;
+    // ... other audio events
+  };
+}
+```
+
+**Location:** `frontend/src/hooks/audio/useAudioEventManager.ts` (~115 LOC)
+
+### useAudioEffects
+
+Manages element hover/click audio (layers over background audio without ducking).
+
+```typescript
+interface UseAudioEffectsOptions {
+  hoverAudioUrl?: string;
+  clickAudioUrl?: string;
+  volume?: number;         // 0-1 (iOS ignores)
+  isHovered: boolean;
+  isActive: boolean;
+  resolveUrl?: (url: string) => string;
+  resetKey?: string;       // Reset on page navigation
+}
+
+interface UseAudioEffectsResult {
+  playClickAudio: () => void;
+  stopAll: () => void;
+}
+```
+
+**Location:** `frontend/src/hooks/useAudioEffects.ts` (~302 LOC)
+
+---
+
+## Database Schema
+
+Audio settings are stored in the `tour_pages` table:
+
+```sql
+-- Added via migration 20260605000001-add-background-audio-settings.js
+ALTER TABLE tour_pages
+ADD COLUMN background_audio_autoplay BOOLEAN NOT NULL DEFAULT true,
+ADD COLUMN background_audio_loop BOOLEAN NOT NULL DEFAULT true,
+ADD COLUMN background_audio_start_time DECIMAL(10, 1),
+ADD COLUMN background_audio_end_time DECIMAL(10, 1);
+```
+
+---
+
+## Key Files Reference
+
+| File | Location | LOC | Purpose |
+|------|----------|-----|---------|
+| `useBackgroundAudioPlayback.ts` | `frontend/src/hooks/` | 220 | Background audio playback control |
+| `useAudioEventManager.ts` | `frontend/src/hooks/audio/` | 115 | Audio event listener management |
+| `useAudioEffects.ts` | `frontend/src/hooks/` | 302 | Element hover/click audio (no ducking) |
+| `backgroundAudioController.ts` | `frontend/src/lib/` | 81 | Audio ducking coordination |
+| `BackgroundSettingsEditor.tsx` | `frontend/src/components/Constructor/` | - | Audio settings UI |
+| `CanvasBackground.tsx` | `frontend/src/components/Constructor/` | - | Audio element rendering |
+| `RuntimePresentation.tsx` | `frontend/src/components/` | - | Runtime audio integration |
+| `constructor.tsx` | `frontend/src/pages/` | - | Constructor audio integration |
+| `AudioPlayerElement.tsx` | `frontend/src/components/UiElements/elements/` | 77 | Audio player with ducking |
+| `VideoPlayerElement.tsx` | `frontend/src/components/UiElements/elements/` | 91 | Video player with ducking |
+
+---
+
+## Troubleshooting
+
+### Audio Won't Play
+1. Verify user has interacted (click/tap) - check `backgroundAudioController.hasInteracted()`
+2. In constructor, verify you're in Interact mode (not Edit mode)
+3. Verify audio URL resolves correctly
+4. Check CORS headers on audio source
+5. Ensure audio format is supported (MP3/OGG/WAV)
+
+### Audio Ducking Not Working
+1. Verify `backgroundAudioController.register()` is called in CanvasBackground
+2. Check `notifyForegroundStart/End` calls in AudioPlayerElement and VideoPlayerElement
+3. Ensure foreground audio count is balanced (start/end pairs)
+
+### Audio Doesn't Loop Correctly
+1. Check if `endTime` is set (uses JS loop instead of native)
+2. Verify `startTime` is valid for seeking
+3. Ensure `timeupdate` event handler is attached
+
+### Memory Leaks
+1. Verify blob URLs are revoked on cleanup
+2. Check `backgroundAudioController.register(null)` on unmount
+3. Ensure event listeners are removed via useAudioEventManager cleanup
diff --git a/documentation/authentication-system.md b/documentation/authentication-system.md
new file mode 100644
index 0000000..847912e
--- /dev/null
+++ b/documentation/authentication-system.md
@@ -0,0 +1,764 @@
+# Authentication System
+
+Complete documentation for the Tour Builder Platform authentication system including local auth, OAuth, JWT tokens, and security features.
+
+## Overview
+
+The platform uses a multi-strategy authentication system built on:
+- **Passport.js** - Authentication middleware with JWT, Google OAuth, and Microsoft OAuth strategies
+- **JWT Tokens** - 6-hour expiration, Bearer token in Authorization header
+- **bcrypt** - Password hashing with 12 salt rounds
+- **Rate Limiting** - In-memory rate limiting for auth endpoints
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Frontend                                 │
+│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
+│  │ Login Page  │  │ authSlice.ts │  │ Axios Interceptors     │ │
+│  │ Register    │  │ (Redux)      │  │ - Token injection      │ │
+│  │ Forgot      │  │              │  │ - 401 handling         │ │
+│  └─────────────┘  └──────────────┘  └────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                         Backend                                  │
+│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
+│  │ auth.js     │  │ AuthService  │  │ Passport.js Strategies │ │
+│  │ (routes)    │  │ (business)   │  │ - JWT                  │ │
+│  │             │  │              │  │ - Google OAuth         │ │
+│  │             │  │              │  │ - Microsoft OAuth      │ │
+│  └─────────────┘  └──────────────┘  └────────────────────────┘ │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │                    UsersDBApi                                ││
+│  │  - Token generation (email verification, password reset)    ││
+│  │  - User CRUD operations                                     ││
+│  └─────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Passport.js Strategies
+
+### JWT Strategy
+
+**File:** `backend/src/auth/auth.ts`
+
+```javascript
+passport.use(new JWTstrategy({
+  passReqToCallback: true,
+  secretOrKey: config.secret_key,
+  jwtFromRequest: ExtractJWT.fromAuthHeaderAsBearerToken()
+}, async (req, token, done) => {
+  // Validates token and checks if user is disabled
+  // Sets req.currentUser for authenticated requests
+}));
+```
+
+| Property | Value |
+|----------|-------|
+| Token Location | `Authorization: Bearer {token}` header |
+| Secret Key | `process.env.SECRET_KEY` |
+| Token Expiration | 6 hours |
+| Validation | Checks user exists and is not disabled |
+
+### Google OAuth Strategy
+
+```javascript
+passport.use(new GoogleStrategy({
+  clientID: config.google.clientId,
+  clientSecret: config.google.clientSecret,
+  callbackURL: config.apiUrl + '/auth/signin/google/callback',
+  passReqToCallback: true
+}));
+```
+
+| Property | Value |
+|----------|-------|
+| Scopes | `profile`, `email` (defined in routes when calling `passport.authenticate()`) |
+| Callback URL | `/api/auth/signin/google/callback` |
+| Auto-Verification | Social auth users are automatically `emailVerified: true` |
+
+### Microsoft OAuth Strategy
+
+```javascript
+passport.use(new MicrosoftStrategy({
+  clientID: config.microsoft.clientId,
+  clientSecret: config.microsoft.clientSecret,
+  callbackURL: config.apiUrl + '/auth/signin/microsoft/callback',
+  passReqToCallback: true
+}));
+```
+
+| Property | Value |
+|----------|-------|
+| Scopes | `https://graph.microsoft.com/user.read openid` (defined in routes when calling `passport.authenticate()`) |
+| Callback URL | `/api/auth/signin/microsoft/callback` |
+| Email Source | `profile._json.mail` or `profile._json.userPrincipalName` |
+
+## API Endpoints
+
+### Authentication Routes
+
+| Method | Endpoint | Auth | Rate Limited | Description |
+|--------|----------|------|--------------|-------------|
+| POST | `/auth/signin/local` | No | Yes (10/15m) | Login with email/password |
+| GET | `/auth/me` | JWT | No | Get current user info |
+| PUT | `/auth/password-reset` | No | No | Reset password with token |
+| PUT | `/auth/password-update` | JWT | No | Change password |
+| POST | `/auth/send-password-reset-email` | No | Yes (5/1h) | Request reset email |
+| POST | `/auth/send-email-address-verification-email` | JWT | No | Resend verification |
+| PUT | `/auth/verify-email` | No | No | Verify email with token |
+| PUT | `/auth/profile` | JWT | No | Update user profile |
+| GET | `/auth/email-configured` | No | No | Check email config |
+| GET | `/auth/signin/google` | No | No | Initiate Google OAuth |
+| GET | `/auth/signin/google/callback` | No | No | Google OAuth callback |
+| GET | `/auth/signin/microsoft` | No | No | Initiate Microsoft OAuth |
+| GET | `/auth/signin/microsoft/callback` | No | No | Microsoft OAuth callback |
+
+### File Endpoints (Public)
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| GET | `/file/download` | No | Download file (backend proxy for local/GCloud) |
+| POST | `/file/presign` | No | Generate presigned URLs for S3 direct downloads |
+| POST | `/file/upload/:table/:field` | JWT | Legacy single-file upload |
+| POST | `/file/upload-sessions/init` | JWT | Initialize chunked upload |
+| PUT | `/file/upload-sessions/:id/chunks/:idx` | JWT | Upload chunk |
+| GET | `/file/upload-sessions/:id` | JWT | Check upload session status |
+| POST | `/file/upload-sessions/:id/finalize` | JWT | Finalize chunked upload |
+
+**Note:** The download and presign endpoints are intentionally public to support runtime asset preloading without authentication. Access control for assets should be implemented at the storage level (S3 bucket policies) if needed.
+
+### Endpoint Details
+
+#### POST /auth/signin/local
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+```
+
+**Response (Success 200):** JWT token string
+
+**Error Codes (400):**
+- `auth.userNotFound` - User doesn't exist
+- `auth.userDisabled` - Account is disabled
+- `auth.wrongPassword` - Incorrect password
+- `auth.userNotVerified` - Email not verified
+
+#### Self-Registration
+
+Self-registration is disabled. The application does not expose
+`POST /auth/signup` and the frontend does not provide a `/register` page. New
+users are created by authorized staff through the Users flow and receive an
+invitation/setup link.
+
+#### GET /auth/me
+
+**Headers:** `Authorization: Bearer {token}`
+
+**Response (Success 200):**
+```json
+{
+  "id": "uuid",
+  "email": "user@example.com",
+  "firstName": "John",
+  "lastName": "Doe",
+  "emailVerified": true,
+  "disabled": false,
+  "provider": "local",
+  "app_role": { "id": "...", "name": "User" },
+  "custom_permissions": []
+}
+```
+
+#### PUT /auth/verify-email
+
+**Request:**
+```json
+{
+  "token": "email_verification_token_40_chars"
+}
+```
+
+**Response (Success 200):** `true`
+
+**Error Codes (400):**
+- `auth.emailAddressVerificationEmail.invalidToken` - Invalid or expired token
+
+#### PUT /auth/password-reset
+
+**Request:**
+```json
+{
+  "token": "password_reset_token_40_chars",
+  "password": "newPassword123"
+}
+```
+
+**Response (Success 200):** User object
+
+**Error Codes (400):**
+- `auth.passwordReset.invalidToken` - Invalid or expired token
+
+#### PUT /auth/password-update
+
+**Headers:** `Authorization: Bearer {token}`
+
+**Request:**
+```json
+{
+  "currentPassword": "oldPassword123",
+  "newPassword": "newPassword123"
+}
+```
+
+**Error Codes (400):**
+- `auth.wrongPassword` - Current password incorrect
+- `auth.passwordUpdate.samePassword` - New password same as old
+
+## Rate Limiting
+
+**File:** `backend/src/middlewares/rateLimiter.js`
+
+| Endpoint | Limiter | Max Requests | Window | Key |
+|----------|---------|--------------|--------|-----|
+| `/auth/signin/local` | `authLimiter` | 10 | 15 minutes | IP address |
+| `/auth/send-password-reset-email` | `passwordResetLimiter` | 5 | 1 hour | IP address |
+
+**Implementation:**
+```javascript
+// backend/src/routes/auth.ts imports from centralized rate limiter
+const {
+  authLimiter: signinLimiter,
+  passwordResetLimiter,
+} = require('../middlewares/rateLimiter');
+
+// Rate limiters are created with createRateLimiter factory
+const authLimiter = createRateLimiter({
+  keyPrefix: 'auth',
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 10,
+  message: 'Too many authentication attempts. Please try again later.',
+  skipFailedRequests: false, // Count failed attempts
+});
+```
+
+- Uses centralized in-memory Map: `rateLimitStore`
+- Key format: `${keyPrefix}:${req.ip}`
+- Adds standard rate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`)
+- Returns 429 status with JSON response when exceeded
+- Automatic cleanup of expired entries every 5 minutes
+- Skips rate limiting in development for localhost
+
+## User Model
+
+**File:** `backend/src/db/models/users.js`
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| id | UUID | Yes | UUIDV4 | Primary key |
+| email | TEXT | Yes | - | Unique, validated as email |
+| password | TEXT | Yes | - | bcrypt hashed |
+| firstName | TEXT | No | null | Trimmed on save |
+| lastName | TEXT | No | null | Trimmed on save |
+| phoneNumber | TEXT | No | null | |
+| disabled | BOOLEAN | No | false | Account status |
+| emailVerified | BOOLEAN | No | false | Verification status |
+| emailVerificationToken | TEXT | No | null | 40-char hex |
+| emailVerificationTokenExpiresAt | DATE | No | null | 24h expiry |
+| passwordResetToken | TEXT | No | null | 40-char hex |
+| passwordResetTokenExpiresAt | DATE | No | null | 24h expiry |
+| provider | TEXT | No | 'local' | local/google/microsoft |
+| app_roleId | UUID | No | null | FK to roles |
+| importHash | STRING(255) | No | null | Unique, for CSV deduplication |
+
+**Note:** The `authenticationUid` field is set dynamically during `createFromAuth()` and `updatePassword()` operations (set to user ID after creation).
+
+### Model Hooks
+
+```javascript
+users.beforeCreate((users) => {
+  // Trim email, firstName, lastName
+  if (users.provider !== 'local') {
+    users.emailVerified = true;  // Auto-verify social auth
+    if (!users.password) {
+      // Generate random password for OAuth users
+      users.password = bcrypt.hashSync(randomPassword, 12);
+    }
+  }
+});
+```
+
+## Token Generation
+
+**File:** `backend/src/db/api/users.js`
+
+### Email Verification Token
+```javascript
+const token = crypto.randomBytes(20).toString('hex');  // 40-char hex
+const TOKEN_EXPIRY_MS = 24 * 60 * 60 * 1000;  // 24 hours
+```
+
+### Password Reset Token
+```javascript
+const token = crypto.randomBytes(20).toString('hex');  // 40-char hex
+const TOKEN_EXPIRY_MS = 24 * 60 * 60 * 1000;  // 24 hours
+```
+
+### JWT Token
+**File:** `backend/src/helpers.js`
+
+```javascript
+static jwtSign(data) {
+  return jwt.sign(data, config.secret_key, { expiresIn: '6h' });
+}
+```
+
+Payload structure:
+```json
+{
+  "user": {
+    "id": "uuid",
+    "email": "user@example.com"
+  }
+}
+```
+
+## Frontend Implementation
+
+### Auth Slice (Redux)
+
+**File:** `frontend/src/stores/authSlice.ts`
+
+```typescript
+interface MainState {
+  isFetching: boolean;
+  errorMessage: string;
+  currentUser: any;
+  token: string;
+  notify: any;  // Contains showNotification, textNotification, typeNotification
+}
+```
+
+### Async Thunks
+
+**loginUser:**
+```typescript
+export const loginUser = createAsyncThunk(
+  'auth/loginUser',
+  async (creds: Record<string, string>, { rejectWithValue }) => {
+    const response = await axios.post('auth/signin/local', creds);
+    return response.data;  // JWT token
+  },
+);
+```
+
+Expected `creds` object: `{ email: string, password: string }`
+
+**findMe:**
+```typescript
+export const findMe = createAsyncThunk('auth/findMe', async () => {
+  const response = await axios.get('auth/me');
+  return response.data;  // Current user
+});
+```
+
+### Token Storage
+
+On successful login:
+```typescript
+builder.addCase(loginUser.fulfilled, (state, action) => {
+  const token = action.payload;
+  const user = jwt.decode(token);
+
+  // Store in both storages
+  sessionStorage.setItem('token', token);
+  sessionStorage.setItem('user', JSON.stringify(user));
+  localStorage.setItem('token', token);
+  localStorage.setItem('user', JSON.stringify(user));
+
+  // Set default header
+  axios.defaults.headers.common['Authorization'] = 'Bearer ' + token;
+});
+```
+
+On logout (reducer action in authSlice):
+```typescript
+logoutUser: (state) => {
+  sessionStorage.removeItem('token');
+  sessionStorage.removeItem('user');
+  localStorage.removeItem('token');
+  localStorage.removeItem('user');
+  axios.defaults.headers.common['Authorization'] = '';  // Set to empty in reducer
+  state.currentUser = null;
+  state.token = '';
+}
+```
+
+### Axios Interceptors
+
+**File:** `frontend/src/pages/_app.tsx`
+
+**Request Interceptor (Token Injection):**
+```typescript
+axios.interceptors.request.use((config) => {
+  if (typeof window !== 'undefined') {
+    const token = sessionStorage.getItem('token') || localStorage.getItem('token');
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+  }
+  return config;
+});
+```
+
+**Response Interceptor (401 Handling + Presigned URL Failure Detection):**
+```typescript
+axios.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (typeof window !== 'undefined') {
+      const status = error?.response?.status;
+      const requestUrl = `${error?.config?.url || ''}`;
+      const isLoginRequest =
+        requestUrl.includes('/auth/signin/local') ||
+        requestUrl.includes('auth/signin/local');
+
+      // Detect presigned S3 URL failures (CORS not configured)
+      // Network errors (status 0) or CORS errors typically indicate S3 CORS issues
+      if (
+        isPresignedS3Url(requestUrl) &&
+        (!status || status === 0 || error.message?.includes('Network Error'))
+      ) {
+        logger.info('[axios] Presigned URL failed, disabling presigned URLs', {
+          url: requestUrl.slice(0, 80),
+        });
+        disablePresignedUrls();  // Falls back to backend proxy
+      }
+
+      if (status === 401 && !isLoginRequest) {
+        // Clear stored tokens
+        sessionStorage.removeItem('token');
+        sessionStorage.removeItem('user');
+        localStorage.removeItem('token');
+        localStorage.removeItem('user');
+        delete axios.defaults.headers.common['Authorization'];
+
+        // Redirect to login if not already there
+        if (!window.location.pathname.includes('/login')) {
+          window.location.href = '/login';
+        }
+      }
+    }
+    return Promise.reject(error);
+  },
+);
+
+// Helper function to detect presigned S3 URLs
+const isPresignedS3Url = (url: string): boolean => {
+  return url.includes('X-Amz-Signature=') || url.includes('x-amz-signature=');
+};
+```
+
+**Presigned URL Fallback:** When S3 CORS is not configured, presigned URL requests fail with network errors. The interceptor detects these failures and automatically disables presigned URLs, falling back to the backend proxy for file downloads.
+```
+
+## Authentication Flows
+
+### Local Login Flow
+
+```
+1. User enters email/password on login.tsx
+2. dispatch(loginUser({ email, password }))
+3. POST /auth/signin/local
+4. Backend validates:
+   - User exists
+   - User not disabled
+   - Email verified (if email configured)
+   - Password matches (bcrypt.compare)
+5. Return JWT token (6h expiration)
+6. Frontend stores token in sessionStorage + localStorage
+7. Set axios Authorization header
+8. dispatch(findMe()) → GET /auth/me
+9. Redirect to /dashboard
+```
+
+### Invitation-Only Account Flow
+
+```
+1. Administrator, Platform Owner, or Account Manager creates a user from Users.
+2. Backend creates the user, assigns the selected role, and sends an invitation/setup email when email is configured.
+3. User opens the setup link.
+4. User sets a password through the password-reset/setup screen.
+5. User can log in with email/password.
+```
+
+### Password Reset Flow
+
+```
+1. User enters email on forgot.tsx
+2. POST /auth/send-password-reset-email
+3. Backend generates passwordResetToken (40-char hex, 24h expiry)
+4. Send email with link: /password-reset?token={token}
+5. User clicks link → PasswordSetOrReset component
+6. User enters new password
+7. PUT /auth/password-reset with token + newPassword
+8. Backend validates token, hashes new password, updates user
+9. Clear token fields
+10. Redirect to /login
+```
+
+### OAuth Flow (Google/Microsoft)
+
+```
+1. User clicks "Sign in with Google/Microsoft"
+2. GET /auth/signin/google (or microsoft)
+3. Passport initiates OAuth flow
+4. User grants permissions
+5. Provider redirects to callback
+6. GET /auth/signin/google/callback?code=...
+7. Backend exchanges code for access token
+8. Retrieve user profile (email, name)
+9. findOrCreate user by email
+10. Auto-set emailVerified: true
+11. Generate JWT token
+12. Redirect to /login?token={jwt}
+13. Frontend extracts token from URL, stores, redirects to /dashboard
+```
+
+### Protected Route Access
+
+```
+1. Frontend makes API request
+2. Axios interceptor adds: Authorization: Bearer {token}
+3. Backend: passport.authenticate('jwt') middleware
+4. JWT strategy validates token signature and expiry
+5. Decode payload: { user: { id, email } }
+6. Query database for user
+7. Check user.disabled - reject if true
+8. Set req.currentUser = user
+9. Proceed to route handler
+```
+
+## Security Features
+
+### Password Security
+
+| Feature | Implementation |
+|---------|----------------|
+| Algorithm | bcrypt |
+| Salt Rounds | 12 |
+| Storage | Hashed only, never plaintext |
+| Comparison | `bcrypt.compare()` (constant-time) |
+
+### Token Security
+
+| Feature | Implementation |
+|---------|----------------|
+| JWT Algorithm | HS256 |
+| Expiration | 6 hours |
+| Secret | Environment variable `SECRET_KEY` |
+| Transmission | Bearer token in Authorization header |
+| Storage | sessionStorage + localStorage |
+
+### Verification Tokens
+
+| Token Type | Length | Format | Expiry |
+|------------|--------|--------|--------|
+| Email Verification | 40 chars | hex | 24 hours |
+| Password Reset | 40 chars | hex | 24 hours |
+
+### User Disabling
+
+- **Field:** `disabled` boolean on users table
+- **JWT Validation:** Strategy rejects disabled users
+- **Auth Check:** Both signin and signup reject disabled users
+- **Use Case:** Admin can disable accounts without deletion
+
+## Protected Routes Pattern
+
+**Backend middleware:**
+```javascript
+const jwtAuth = passport.authenticate('jwt', { session: false });
+
+// Protected routes
+app.use('/api/users', jwtAuth, usersRoutes);
+app.use('/api/roles', jwtAuth, rolesRoutes);
+app.use('/api/permissions', jwtAuth, permissionsRoutes);
+```
+
+**Runtime routes with optional auth (environment-based):**
+
+The frontend sends `X-Runtime-Environment` header to indicate the environment context:
+- `production` - Public tour pages (no auth required for GET requests)
+- `stage` - Preview environment (requires authentication)
+- `dev` - Constructor editing (requires authentication)
+
+```javascript
+const requireRuntimeReadOrAuth = (req, res, next) => {
+  const headerEnvironment = req.runtimeContext?.headerEnvironment;
+  const headerProjectSlug = req.runtimeContext?.headerProjectSlug;
+  const isReadOnlyRequest = ['GET', 'OPTIONS'].includes(req.method);
+
+  // Only production is public. Stage requires authentication (workspace for review).
+  const isPublicEnvironment = headerEnvironment === 'production';
+
+  if (isPublicEnvironment && isReadOnlyRequest && !isPrivateProductionPresentation(headerProjectSlug)) {
+    req.isRuntimePublicRequest = true;  // Allow public read access
+    return next();
+  }
+  // Private production presentations require JWT + staff permission
+  // or a production_presentation_access grant.
+  return jwtAuth(req, res, next);
+};
+```
+
+Private production presentation visibility and customer grants are stored in the
+database separately from broad RBAC permissions. See
+[private-production-presentations.md](./private-production-presentations.md).
+
+**Entities with public read access (production environment only):**
+- `projects` - Project metadata (filtered fields)
+- `tour_pages` - Page content including `ui_schema_json`
+- `project_audio_tracks` - Background audio tracks
+
+**File endpoints (no auth required):**
+```javascript
+// No authentication - used for runtime asset loading
+GET /api/file/download?privateUrl={path}  // Backend proxy for local/GCloud storage
+POST /api/file/presign                     // Generate presigned URLs for S3 direct download
+```
+
+## Configuration
+
+**File:** `backend/src/config.ts`
+
+### Role Configuration
+```javascript
+roles: {
+  admin: 'Administrator',
+  user: 'Analytics Viewer',
+}
+```
+
+Self-registration is disabled, so `config.roles.user` is not used by a public
+signup endpoint.
+
+### Password Configuration
+```javascript
+bcrypt: {
+  saltRounds: 12  // bcrypt hashing rounds
+}
+```
+
+### Seed Credentials
+
+Seeded user credentials are loaded from backend configuration and environment
+values. The frontend login page must not display or prefill seeded credentials in
+any environment.
+
+## Environment Variables
+
+**Required:**
+```bash
+# JWT
+SECRET_KEY=your_secret_key_here
+
+# Google OAuth
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+
+# Microsoft OAuth
+MS_CLIENT_ID=your_microsoft_client_id
+MS_CLIENT_SECRET=your_microsoft_client_secret
+
+# Email (for verification/reset)
+EMAIL_USER=your_smtp_username
+EMAIL_PASS=your_smtp_password
+```
+
+**Frontend:**
+```bash
+NEXT_PUBLIC_BACK_API=http://localhost:3000/api
+```
+
+## Error Handling
+
+### Validation Errors (400)
+```javascript
+throw new ValidationError('auth.emailAlreadyInUse');
+throw new ValidationError('auth.userNotFound');
+throw new ValidationError('auth.wrongPassword');
+throw new ValidationError('auth.userNotVerified');
+```
+
+### Forbidden Errors (403)
+```javascript
+throw new ForbiddenError();  // JWT invalid/missing
+```
+
+### Rate Limit Errors (429)
+```javascript
+res.status(429).send({
+  message: 'Too many requests. Please try again later.',
+});
+```
+
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| `backend/src/auth/auth.ts` | Passport.js strategy configuration |
+| `backend/src/routes/auth.ts` | Authentication route handlers |
+| `backend/src/services/auth.ts` | Authentication business logic |
+| `backend/src/middlewares/rateLimiter.ts` | Centralized rate limiting middleware |
+| `backend/src/db/api/users.js` | User database operations |
+| `backend/src/db/models/users.js` | User Sequelize model |
+| `backend/src/config.ts` | Auth configuration (bcrypt, secrets) |
+| `backend/src/helpers.ts` | JWT signing helper |
+| `backend/src/middlewares/runtime-context.ts` | Runtime environment context (X-Runtime-Environment header) |
+| `backend/src/middlewares/runtime-public.ts` | Public runtime access filtering and field sanitization |
+| `frontend/src/stores/authSlice.ts` | Redux auth state |
+| `frontend/src/pages/login.tsx` | Login page |
+| `frontend/src/pages/forgot.tsx` | Forgot password page |
+| `frontend/src/pages/verify-email.tsx` | Email verification page |
+| `frontend/src/components/PasswordSetOrReset.tsx` | Password reset component |
+| `frontend/src/pages/_app.tsx` | Axios interceptors, presigned URL failure detection |
+| `frontend/src/lib/assetUrl.ts` | Presigned URL management and fallback logic |
+
+## Troubleshooting
+
+### Common Issues
+
+**"auth.userNotVerified" error:**
+- Email verification is required when email is configured
+- Check user's `emailVerified` field in database
+- Resend verification email via `/auth/send-email-address-verification-email`
+
+**401 errors on all requests:**
+- Token may be expired (6h limit)
+- Token may be malformed
+- Check Authorization header format: `Bearer {token}`
+- Verify SECRET_KEY matches between token generation and validation
+
+**Rate limit exceeded (429):**
+- Wait for window to expire (15 min for signin, 1 hour for signup/reset)
+- Rate limits are per IP address
+- Consider adjusting limits in `backend/src/routes/auth.ts`
+
+**OAuth callback fails:**
+- Verify callback URLs match in provider console
+- Check client ID and secret in environment variables
+- Ensure OAuth scopes are properly configured
+
+**Token not persisting after refresh:**
+- Check both sessionStorage and localStorage
+- Verify axios interceptors are properly attached
+- Check for errors in browser console
diff --git a/documentation/custom-domains-apache.md b/documentation/custom-domains-apache.md
new file mode 100644
index 0000000..08f4cb8
--- /dev/null
+++ b/documentation/custom-domains-apache.md
@@ -0,0 +1,336 @@
+# Custom Domains via Apache on the VM
+
+Operational plan for serving public production presentations on customer-owned
+hostnames without changing Cloudflare configuration.
+
+## Current VM Facts
+
+The checked VM uses this public IPv4 address:
+
+```text
+185.8.107.221
+```
+
+The current runtime ports are:
+
+| Component | Port | Notes |
+|-----------|------|-------|
+| Apache | 80 | Public HTTP reverse proxy |
+| Frontend | 3001 | Next.js production server |
+| Backend | 3000 | Express API |
+
+Apache currently listens on `:80`; `:443` is not enabled on the VM until a
+certificate is issued and an SSL virtual host is created.
+
+The existing Apache proxy pattern is:
+
+```text
+/api/* -> http://127.0.0.1:3000
+/*     -> http://127.0.0.1:3001
+```
+
+Cloudflare settings are out of scope for this workflow. Do not rely on a
+customer CNAME to `tbp.flatlogic.app`, because that hostname may be proxied by
+Cloudflare and reject unknown customer hostnames before the request reaches the
+VM.
+
+## Customer DNS Setup
+
+For each customer hostname, ask the customer to create an `A` record pointing
+directly to the VM public IP:
+
+```text
+Type: A
+Name: presentation
+Value: 185.8.107.221
+TTL: 300 or Auto
+Proxy/CDN: DNS only / Off
+```
+
+For the full hostname:
+
+```text
+presentation.customer.com A 185.8.107.221
+```
+
+Customer-side notes:
+
+- DNS records cannot contain paths such as `/p/presentation`.
+- Do not configure an HTTP redirect to `tbp.flatlogic.app/p/...`.
+- If the customer uses Cloudflare or another CDN, start with DNS-only mode.
+- The customer can use multiple hostnames; each hostname should point to the
+  same VM IP and will be routed by our host/path mapping.
+
+## Required Route Data
+
+Before VM and app setup, collect these values:
+
+```text
+CUSTOM_DOMAIN=presentation.customer.com
+CERTBOT_EMAIL=admin@flatlogic.com
+ROUTES:
+  /        -> presentation
+  /normal  -> presentation-normal
+  /premium -> presentation-premium
+```
+
+Routes are resolved by `hostname + path`, not by DNS. The same customer can
+have several hostnames and several paths per hostname.
+
+Example mapping:
+
+```text
+presentation.customer.com | /        | presentation
+presentation.customer.com | /normal  | presentation-normal
+presentation.customer.com | /premium | presentation-premium
+hotel-a.customer.com      | /        | hotel-a-tour
+hotel-b.customer.com      | /        | hotel-b-tour
+```
+
+## DNS Verification
+
+After the customer creates the DNS record, verify resolution from the VM:
+
+```bash
+dig +short presentation.customer.com
+```
+
+Expected output:
+
+```text
+185.8.107.221
+```
+
+Verify HTTP reaches the VM:
+
+```bash
+curl -I http://presentation.customer.com
+curl -I -H 'Host: presentation.customer.com' http://127.0.0.1/
+```
+
+Before HTTPS is configured, only HTTP is expected to work.
+
+## Apache Virtual Host
+
+Create a customer-specific Apache site:
+
+```bash
+sudo nano /etc/apache2/sites-available/custom-presentation.customer.com.conf
+```
+
+Use this HTTP virtual host as the starting point:
+
+```apache
+<VirtualHost *:80>
+  ServerName presentation.customer.com
+
+  ProxyPreserveHost On
+  ProxyRequests Off
+
+  RewriteEngine On
+
+  RewriteRule ^/api(/.*)?$ http://127.0.0.1:3000$0 [P,L]
+
+  RewriteCond %{HTTP:Upgrade} =websocket [NC]
+  RewriteRule /(.*) ws://127.0.0.1:3001/$1 [P,L]
+
+  RewriteCond %{HTTP:Upgrade} !=websocket [NC]
+  RewriteRule /(.*) http://127.0.0.1:3001/$1 [P,L]
+
+  ProxyPassReverse /api http://127.0.0.1:3000/api
+  ProxyPassReverse / http://127.0.0.1:3001/
+
+  ErrorLog /var/log/apache2/custom-presentation.customer.com-error.log
+  CustomLog /var/log/apache2/custom-presentation.customer.com-access.log combined
+</VirtualHost>
+```
+
+Enable and reload:
+
+```bash
+sudo a2ensite custom-presentation.customer.com.conf
+sudo apache2ctl configtest
+sudo systemctl reload apache2
+```
+
+## HTTPS with Certbot
+
+Install Certbot if needed:
+
+```bash
+sudo apt update
+sudo apt install -y certbot python3-certbot-apache
+```
+
+Issue the certificate:
+
+```bash
+sudo certbot --apache \
+  -d presentation.customer.com \
+  --email admin@flatlogic.com \
+  --agree-tos \
+  --no-eff-email
+```
+
+Verify Apache and certificate state:
+
+```bash
+sudo ss -ltnp | grep -E ':80|:443'
+sudo certbot certificates
+curl -I https://presentation.customer.com
+sudo certbot renew --dry-run
+```
+
+After Certbot succeeds, Apache should listen on `:443` and serve HTTPS for the
+customer hostname.
+
+## Application Changes
+
+The application needs a host/path routing layer for public production runtime.
+
+### Backend Mapping
+
+Add a backend entity such as `custom_domain_routes` with these minimum fields:
+
+```text
+hostname      text, required
+path          text, required
+project_slug  text, required
+environment   text, default production
+is_active     boolean, default true
+created_at
+updated_at
+```
+
+Required constraint:
+
+```text
+UNIQUE(hostname, path)
+```
+
+Normalization rules:
+
+- `hostname`: lowercase, no port.
+- `path`: starts with `/`; remove trailing slash except for `/`.
+- `environment`: first version should use only `production`.
+
+### Backend Resolve Endpoint
+
+Add a public endpoint:
+
+```text
+GET /api/runtime-context/custom-domain/resolve?path=/normal
+```
+
+Behavior:
+
+```text
+hostname = request Host header / req.hostname
+path = normalized query path
+find active route by hostname + path
+return { projectSlug, environment }
+```
+
+Failure behavior:
+
+```text
+400 for invalid path
+404 if no active mapping exists
+```
+
+Security requirements:
+
+- Do not accept hostname from query or body.
+- Use only the request host that reached Apache/backend.
+- Do not expose stage, constructor, or admin through customer hostnames.
+- Return only the data needed to render the public runtime.
+
+### Frontend Custom-Domain Route
+
+Add a public catch-all route for customer-domain paths:
+
+```text
+/
+/normal
+/premium
+```
+
+Runtime behavior:
+
+```text
+1. Read window.location.pathname.
+2. Detect that the current host is not a standard platform host.
+3. Call /api/runtime-context/custom-domain/resolve?path=<pathname>.
+4. Render <RuntimePresentation projectSlug={projectSlug} environment="production" />.
+```
+
+Keep existing platform routes unchanged:
+
+```text
+/p/[projectSlug]
+/p/[projectSlug]/stage
+/constructor
+```
+
+## End-to-End Checks
+
+DNS:
+
+```bash
+dig +short presentation.customer.com
+```
+
+Apache:
+
+```bash
+sudo apache2ctl -S
+sudo ss -ltnp | grep -E ':80|:443|:3000|:3001'
+```
+
+HTTP and HTTPS:
+
+```bash
+curl -I http://presentation.customer.com
+curl -I https://presentation.customer.com
+```
+
+Routes:
+
+```bash
+curl -I https://presentation.customer.com/
+curl -I https://presentation.customer.com/normal
+curl -I https://presentation.customer.com/premium
+curl -I https://presentation.customer.com/api/health
+```
+
+Direct upstream checks:
+
+```bash
+curl -I http://127.0.0.1:3001
+curl -I http://127.0.0.1:3000/api/health
+```
+
+Expected outcome:
+
+- Customer hostname resolves to `185.8.107.221`.
+- HTTPS certificate matches the customer hostname.
+- `/api/health` works through the customer hostname.
+- `/`, `/normal`, and `/premium` route to configured production
+  presentations.
+- Browser URL remains on the customer hostname.
+
+## Rollout Strategy
+
+1. Configure one test customer hostname.
+2. Start with a single route: `/ -> one project slug`.
+3. Verify DNS, Apache, HTTPS, API, assets, and first page load.
+4. Add `/normal` and `/premium`.
+5. Verify images, video, audio, and service worker behavior.
+6. Repeat for additional customer hostnames.
+
+## Out of Scope
+
+- Cloudflare custom hostnames or DNS changes in the `flatlogic.app` zone.
+- Customer-side HTTP redirects.
+- Stage, constructor, or admin access through customer domains.
+- UI for managing custom-domain routes in the first version.
diff --git a/documentation/db-cleanup-audit.md b/documentation/db-cleanup-audit.md
new file mode 100644
index 0000000..e3ffdb4
--- /dev/null
+++ b/documentation/db-cleanup-audit.md
@@ -0,0 +1,77 @@
+# DB Cleanup Audit
+
+This document describes the non-destructive database cleanup audit for finding
+orphan records, legacy schema leftovers, and soft-deleted row volume.
+
+## Manual Audit
+
+The cleanup audit is intentionally run as one-time read-only SQL on the target
+database instead of a permanent application command. It should check the same
+categories listed below and must not delete or update rows.
+
+If rows are found, first capture affected-row details and a backup/export, then
+apply cleanup through a reviewed migration or operations runbook.
+
+## What It Checks
+
+Orphan and broken-reference checks:
+
+- active `asset_variants` with missing or soft-deleted `assets` parents
+- active `pwa_caches` with missing or soft-deleted `projects` parents
+- active `access_logs` with missing or soft-deleted `projects` or `users`
+  parents
+- active `access_logs` with `NULL projectId` or `NULL userId` as warnings,
+  because admin/system or public/anonymous access may be valid
+- active `production_presentation_access` grants with missing, soft-deleted, or
+  `NULL` `projectId`/`userId`
+
+Legacy schema checks:
+
+- old normalized constructor tables: `page_elements`, `page_links`,
+  `transitions`
+- known removed columns: `assets.is_deleted`, `assets.deleted_at_time`,
+  `projects.is_deleted`, `projects.deleted_at_time`, `projects.phase`,
+  `projects.entry_page_slug`, `projects.transition_settings`
+
+Soft-delete summary:
+
+- every table with a `deletedAt` column is scanned for soft-deleted row count
+- the report includes oldest and newest `deletedAt` timestamps per table
+
+## Retention Policy
+
+Keep soft-deleted rows indefinitely by default.
+
+Reason: the project uses Sequelize paranoid models, deletion volume is expected
+to be low, and restoring accidental deletes is more valuable than speculative
+storage cleanup.
+
+Any physical deletion must be a separate migration or operations runbook with:
+
+- a fresh backup
+- explicit affected-row query
+- rollback or restore plan
+- table-specific retention threshold
+
+## Prevention
+
+Asset deletion is handled in `AssetsService`. Because PostgreSQL foreign-key
+`ON DELETE CASCADE` does not fire for Sequelize paranoid soft deletes,
+`AssetsService.remove()` and `AssetsService.deleteByIds()` soft-delete active
+`asset_variants` rows in the same transaction as the parent `assets` soft
+delete. This prevents active variants from remaining attached to soft-deleted
+assets after commit.
+
+## Local Audit Result
+
+Last local run: 2026-07-02.
+
+Result:
+
+- failed orphan checks: `0`
+- warning orphan checks: `0`
+- legacy schema candidates: `0`
+- tables with soft-deleted rows: `4`
+
+Soft-deleted rows were present in local `assets`, `projects`, `tour_pages`, and
+`production_presentation_access`. No deletion was performed.
diff --git a/documentation/deployment-vm.md b/documentation/deployment-vm.md
new file mode 100644
index 0000000..c031299
--- /dev/null
+++ b/documentation/deployment-vm.md
@@ -0,0 +1,299 @@
+# VM Deployment Runbook
+
+Operational notes for the standard Flatlogic VM deployment used by this
+project. This document describes the VM runtime layout, health checks, and the
+June 2026 `503 Service Unavailable` recovery path.
+
+## Runtime Topology
+
+The standard VM runs the app behind Apache and Cloudflare:
+
+```
+Cloudflare
+  -> Apache :80
+    -> Frontend Next.js production server :3001
+    -> Backend API :3000
+```
+
+Do not assume older local development ports on the VM. The standard port split
+is frontend `3001` and backend `3000`:
+
+| Component | VM process | Port | Notes |
+|-----------|------------|------|-------|
+| Apache | `apache2` | 80 | Public entrypoint, reverse proxy |
+| Frontend | `frontend-dev` | 3001 | `npm run build`, then `npm run start` |
+| Backend | `backend-dev` | 3000 | `NODE_ENV=dev_stage npm run start` |
+| Telemetry | `fl-telemetry` | 4317/4318 | Executor telemetry daemon |
+| Executor | `fl-executor` | n/a | VM command/executor bridge |
+
+The backend returns `401 Unauthorized` for protected API endpoints without a
+JWT. A `401` from `http://127.0.0.1:3000/api/...` means the backend is alive.
+The backend default is port `3000` for `dev_stage`; an explicit `PORT` env var
+overrides that when needed.
+
+## Process Manager
+
+PM2 is managed by systemd:
+
+```bash
+sudo systemctl status pm2-ubuntu --no-pager
+pm2 status
+```
+
+Expected PM2 apps:
+
+| Name | Purpose |
+|------|---------|
+| `frontend-dev` | Next.js frontend production server |
+| `backend-dev` | Express API, migrations, seed, watcher |
+| `fl-telemetry` | Local telemetry daemon |
+| `fl-executor` | Standard VM executor bridge |
+
+The frontend PM2 app name may remain `frontend-dev` for compatibility with the
+standard VM image, but the process should run the production script. Build the
+VM frontend with:
+
+```bash
+cd /home/ubuntu/executor/workspace/frontend
+npm run build
+```
+
+Start it with:
+
+```bash
+FRONT_PORT=3001 npm run start
+```
+
+The production frontend is a Next.js server build served by `next start`.
+Do not run the VM frontend with `next dev`; the dev server displays the Next.js
+dev indicator in presentations.
+
+## Frontend Release Deploys
+
+Automatic VM pulls should deploy the frontend as immutable releases instead of
+rebuilding in the live workspace. The executor VCS layer builds a fresh copy
+under:
+
+```bash
+/home/ubuntu/executor/frontend-releases/<timestamp>-<git-sha>/frontend
+```
+
+The deploy order is:
+
+1. Pull the requested branch into `/home/ubuntu/executor/workspace`.
+2. Archive `HEAD` into a new release directory.
+3. Copy frontend env files from the live workspace when present:
+   `.env`, `.env.local`, `.env.production`, `.env.production.local`.
+4. Run `npm ci`.
+5. Run `npm run build`.
+6. Remove non-runtime build caches from the new release:
+   `.next`, `.turbo`, `build/cache`. Production runtime assets stay in
+   `build`; local `next dev --turbopack` uses `.next` to avoid conflicts with
+   production build manifests.
+7. Switch `frontend-dev` to the new release with
+   `FRONT_PORT=3001 pm2 start npm --name frontend-dev -- run start`.
+8. Save PM2 and remove old frontend releases.
+
+The active frontend release is the PM2 `frontend-dev` working directory. Check
+it with:
+
+```bash
+pm2 jlist | jq '.[] | select(.name=="frontend-dev") | {
+  cwd:.pm2_env.pm_cwd,
+  script:.pm2_env.pm_exec_path,
+  args:.pm2_env.args,
+  env:{FRONT_PORT:.pm2_env.FRONT_PORT}
+}'
+```
+
+Retention defaults to the latest 2 release directories. Override it by setting
+`FRONTEND_RELEASES_KEEP` for the executor process before deploy. Do not delete
+the active release directory; `next start` serves production assets from its
+`build` directory.
+
+Manual rollback is possible by starting `frontend-dev` from an older retained
+release:
+
+```bash
+cd /home/ubuntu/executor/frontend-releases/<release-id>/frontend
+pm2 delete frontend-dev
+FRONT_PORT=3001 pm2 start npm --name frontend-dev -- run start
+pm2 save --force
+```
+
+The PM2 dump is stored at:
+
+```bash
+~/.pm2/dump.pm2
+```
+
+This file contains environment variables and may contain secrets. Do not paste
+it into public tools or tickets without redacting tokens, DB passwords, SMTP
+credentials, API keys, and tunnel credentials.
+
+## Health Checks
+
+Use these checks after a deploy or incident:
+
+```bash
+df -h
+df -ih
+free -h
+sudo ss -ltnp | grep -E ':80|:3001|:3000|:4317|:4318'
+curl -I http://127.0.0.1:3001
+curl -I http://127.0.0.1:3000/api/auth/me
+curl -I http://tbp.flatlogic.app
+pm2 status
+```
+
+Expected healthy responses:
+
+- `http://127.0.0.1:3001` returns `200 OK`.
+- `http://127.0.0.1:3000/api/auth/me` returns `401 Unauthorized` without JWT.
+- `http://tbp.flatlogic.app` returns `200 OK`.
+- PM2 shows all four apps `online`.
+
+## Recovering From Apache `503 Service Unavailable`
+
+If Apache returns:
+
+```text
+Service Unavailable
+Apache/2.4.x Server at tbp.flatlogic.app Port 80
+```
+
+first check whether upstream app processes are listening:
+
+```bash
+sudo ss -ltnp | grep -E ':80|:3001|:3000'
+curl -I http://127.0.0.1:3001
+curl -I http://127.0.0.1:3000/api/auth/me
+sudo systemctl status pm2-ubuntu --no-pager
+```
+
+If Apache is listening but `3001` and `3000` are not, PM2 did not restore or was
+stopped. Restart it:
+
+```bash
+sudo systemctl reset-failed pm2-ubuntu
+sudo systemctl restart pm2-ubuntu
+pm2 status
+```
+
+Then re-run the health checks.
+
+## OOM-Kill Diagnosis
+
+A VM can have enough disk and still fail if the kernel kills PM2 or a child
+process because memory spikes. Check kernel logs:
+
+```bash
+journalctl -k --since "YYYY-MM-DD HH:MM" --until "YYYY-MM-DD HH:MM" \
+  | grep -Ei 'oom|killed process|out of memory'
+```
+
+Known June 2026 incident:
+
+- `pm2-ubuntu.service` failed with `Result: oom-kill`.
+- Kernel killed `ffmpeg`.
+- `ffmpeg` used about 3.3 GiB RSS on a 3.8 GiB RAM VM.
+- PM2 then stopped `frontend-dev`, `backend-dev`, `fl-telemetry`, and
+  `fl-executor`.
+
+This points to reversed video generation rather than Apache, disk space, or
+frontend routing.
+
+## FFmpeg and Reverse Video Generation
+
+The backend uses bundled `ffmpeg-static`/`ffprobe-static` via
+`backend/src/services/videoProcessing.ts`; manual OS-level FFmpeg installation
+is not required for this project.
+
+Reverse video generation can be memory-heavy for large videos. Operational
+guardrails:
+
+- FFmpeg reversal is serialized by `videoProcessing.reverseVideo()`: only one
+  FFmpeg process runs at a time in the backend process, and additional reverse
+  generation requests wait in an in-process queue.
+- FFmpeg reversal uses `-threads 1`.
+- FFmpeg reversal has a hard timeout (`FFMPEG_REVERSE_TIMEOUT_MS`, default
+  `600000`, exposed as `config.resilience.ffmpeg.reverseTimeoutMs`) and kills
+  the child process if it exceeds the limit.
+- FFmpeg reversal is protected by an in-process circuit breaker
+  (`FFMPEG_BREAKER_FAILURE_THRESHOLD`, `FFMPEG_BREAKER_COOLDOWN_MS`,
+  `FFMPEG_BREAKER_SUCCESS_THRESHOLD`, exposed under
+  `config.resilience.ffmpeg.breaker`) so repeated media failures stop launching
+  new heavy jobs during the cooldown window.
+- FFprobe metadata extraction has a timeout (`FFPROBE_TIMEOUT_MS`, default
+  `30000`, exposed as `config.resilience.ffmpeg.ffprobeTimeoutMs`).
+- `TourPagesService` deduplicates reverse generation for the same source video
+  storage key.
+- Treat large source videos as risky on small VMs.
+- Check backend PM2 logs for `ffmpeg` or publish/save background errors.
+- If the VM OOMs, inspect kernel logs before changing Apache or database config.
+
+Remaining hardening work and follow-up:
+
+- Add input duration/resolution/size checks before reversal.
+- Structured logs now include reverse-video input/output size and probed media
+  metadata. Continue tuning rejection thresholds as real VM media patterns are
+  observed.
+- Consider running media processing in a separate worker with memory limits.
+
+## Logs
+
+Useful log commands:
+
+```bash
+sudo journalctl -u pm2-ubuntu -n 200 --no-pager
+pm2 logs frontend-dev --lines 100
+pm2 logs backend-dev --lines 100
+pm2 logs fl-executor --lines 100
+pm2 logs fl-telemetry --lines 100
+sudo tail -n 100 /var/log/apache2/error.log
+```
+
+`pm2 logs` tails by default. Press `Ctrl-C` before running the next command.
+
+## Executor Notes
+
+The standard VM `executor.js` in `~/executor` is not the web app startup script.
+It handles VM commands, VCS operations, AI runner prompts, screenshots, and
+telemetry. Starting it manually does not start the frontend/backend app.
+
+Executor workspace path:
+
+```bash
+/home/ubuntu/executor/workspace
+```
+
+The executor can perform git operations when commanded, including reset/clean
+workflows through VCS commands. Do not run executor commands blindly when the
+goal is only to restore the web app. Use PM2/systemd for process recovery.
+
+## Node Version
+
+The project requirement is Node.js 20.x LTS. Some standard VMs may report
+`/usr/bin/node` as Node 22 in PM2. If startup fails after a system update,
+verify:
+
+```bash
+node -v
+which node
+pm2 describe backend-dev
+pm2 describe frontend-dev
+```
+
+Changing the VM Node version should be coordinated with PM2 startup paths and a
+full frontend/backend build check.
+
+## Persistence
+
+After changing PM2 process definitions, save the process list:
+
+```bash
+pm2 save
+```
+
+For an incident-only restart where the process definitions were unchanged,
+`pm2 save` is still safe and keeps the current expected app list for reboot.
diff --git a/documentation/email-notification-service.md b/documentation/email-notification-service.md
new file mode 100644
index 0000000..976f148
--- /dev/null
+++ b/documentation/email-notification-service.md
@@ -0,0 +1,476 @@
+# Email & Notification Service
+
+Complete documentation for the Tour Builder Platform's email and notification system including Nodemailer/SES integration, verification emails, and invitations.
+
+## Overview
+
+The platform implements a transactional email system using Nodemailer with AWS SES (Simple Email Service) for reliable email delivery. The system handles user verification, password resets, and team invitations.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      Email Service Architecture                              │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                         Email Triggers                                  │ │
+│  │                                                                         │ │
+│  │   User Signup ──────────┐                                              │ │
+│  │   Password Reset ───────┼──> AuthService ──> EmailSender ──> AWS SES  │ │
+│  │   User Invitation ──────┘                                              │ │
+│  │   Email Verification ───────────────────────────────────────────────>  │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                      Email Templates                                    │ │
+│  │                                                                         │ │
+│  │   ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐       │ │
+│  │   │ Address         │  │ Password        │  │ Invitation      │       │ │
+│  │   │ Verification    │  │ Reset           │  │                 │       │ │
+│  │   └─────────────────┘  └─────────────────┘  └─────────────────┘       │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `EMAIL_USER` | SMTP username (AWS SES SMTP credentials) | Yes |
+| `EMAIL_PASS` | SMTP password (AWS SES SMTP credentials) | Yes |
+| `EMAIL_TLS_REJECT_UNAUTHORIZED` | TLS certificate validation (`true`/`false`) | No (default: `true`) |
+
+### Config Settings
+
+**Source:** `backend/src/config.ts`
+
+```javascript
+email: {
+  from: 'Tour Builder Platform <app@flatlogic.app>',
+  host: 'email-smtp.us-east-1.amazonaws.com',
+  port: 587,
+  auth: {
+    user: process.env.EMAIL_USER || '',
+    pass: process.env.EMAIL_PASS,
+  },
+  tls: {
+    rejectUnauthorized: process.env.EMAIL_TLS_REJECT_UNAUTHORIZED !== 'false',
+  }
+}
+```
+
+### AWS SES Configuration
+
+The system uses AWS SES SMTP interface in `us-east-1` region:
+- **Host:** `email-smtp.us-east-1.amazonaws.com`
+- **Port:** 587 (TLS)
+- **Configuration Set:** `flatlogic-app` (for tracking/analytics)
+
+## Email Service Class
+
+**Source:** `backend/src/services/email/index.ts`
+
+```typescript
+import nodemailer from 'nodemailer';
+
+export default class EmailSender {
+  constructor(private readonly email: EmailTemplate) {}
+
+  async send(): Promise<EmailSendResult> {
+    // Validates: email, to, subject, html
+    const htmlContent = await this.email.html();
+    const transporter = nodemailer.createTransport(this.transportConfig);
+
+    const mailOptions = {
+      from: this.from,
+      to: this.email.to,
+      subject: this.email.subject,
+      html: htmlContent,
+      headers: {
+        'X-SES-CONFIGURATION-SET': 'flatlogic-app',
+      },
+    };
+
+    return transporter.sendMail(mailOptions);
+  }
+
+  static get isConfigured(): boolean {
+    return Boolean(config.email.auth.pass && config.email.auth.user);
+  }
+}
+```
+
+### Configuration Check
+
+The `EmailSender.isConfigured` static property checks if email credentials are set. When email is not configured:
+- Email verification is skipped when email delivery is disabled
+- Users are automatically marked as verified
+- Password reset/invitation emails are not sent
+
+## Email Types
+
+### 1. Email Address Verification
+
+**Source:** `backend/src/services/email/list/addressVerification.ts`
+
+**Triggered by:**
+- Manual verification request (`POST /api/auth/send-email-address-verification-email`)
+
+**Template:** `backend/src/services/email/htmlTemplates/addressVerification/emailAddressVerification.html`
+
+**Template Variables:**
+| Variable | Description |
+|----------|-------------|
+| `{appTitle}` | Application name ("Tour Builder Platform") |
+| `{signupUrl}` | Verification link with token |
+
+> **Note:** The code attempts to replace `{to}` but this placeholder is not present in the HTML template.
+
+**Token Generation:**
+```javascript
+// UsersDBApi._generateToken
+const token = crypto.randomBytes(20).toString('hex');
+const tokenExpiresAt = Date.now() + (24 * 60 * 60 * 1000); // 24 hours
+
+// Stored in users table:
+// - emailVerificationToken
+// - emailVerificationTokenExpiresAt
+```
+
+### 2. Password Reset
+
+**Source:** `backend/src/services/email/list/passwordReset.ts`
+
+**Triggered by:**
+- Password reset request (`POST /api/auth/send-password-reset-email`)
+
+**Template:** `backend/src/services/email/htmlTemplates/passwordReset/passwordResetEmail.html`
+
+**Template Variables:**
+| Variable | Description |
+|----------|-------------|
+| `{appTitle}` | Application name |
+| `{resetUrl}` | Password reset link with token |
+| `{accountName}` | User's email address |
+
+**Token Generation:**
+```javascript
+// Stored in users table:
+// - passwordResetToken
+// - passwordResetTokenExpiresAt (24 hours)
+```
+
+### 3. User Invitation
+
+**Source:** `backend/src/services/email/list/invitation.ts`
+
+**Triggered by:**
+- User creation with `sendInvitationEmails: true`
+- Bulk user import
+
+**Template:** `backend/src/services/email/htmlTemplates/invitation/invitationTemplate.html`
+
+**Template Variables:**
+| Variable | Description |
+|----------|-------------|
+| `{appTitle}` | Application name |
+| `{signupUrl}` | Invitation link (password reset link with `&invitation=true`) |
+
+> **Note:** The code attempts to replace `{to}` but this placeholder is not present in the HTML template.
+
+**Usage in UsersService:**
+```javascript
+// backend/src/services/users.ts
+if (emailsToInvite && emailsToInvite.length) {
+  AuthService.sendPasswordResetEmail(email, 'invitation', host);
+}
+```
+
+## HTML Template Structure
+
+All email templates follow a consistent structure:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <style>
+        .email-container { max-width: 600px; margin: auto; }
+        .email-header { background-color: #3498db; color: #fff; padding: 16px; }
+        .email-body { padding: 16px; }
+        .email-footer { background-color: #f7fafc; padding: 16px; }
+        .btn-primary { background-color: #3498db; color: #fff; padding: 8px 16px; }
+    </style>
+</head>
+<body>
+    <div class="email-container">
+        <div class="email-header">Welcome to {appTitle}!</div>
+        <div class="email-body"><!-- Content --></div>
+        <div class="email-footer">Thanks, The {appTitle} Team</div>
+    </div>
+</body>
+</html>
+```
+
+## Notification System
+
+### Message Lookup
+
+**Source:** `backend/src/services/notifications/helpers.js`
+
+The notification system uses a key-based lookup for all user-facing messages:
+
+```javascript
+const { getNotification } = require('./notifications/helpers');
+
+// Usage
+getNotification('emails.invitation.subject', appTitle);
+// Returns: "You've been invited to Tour Builder Platform"
+```
+
+### Message Catalog
+
+**Source:** `backend/src/services/notifications/list.ts`
+
+| Key | Message |
+|-----|---------|
+| `app.title` | "Tour Builder Platform" |
+| `emails.invitation.subject` | "You've been invited to {0}" |
+| `emails.emailAddressVerification.subject` | "Verify your email for {0}" |
+| `emails.passwordReset.subject` | "Reset your password for {0}" |
+| `auth.userNotVerified` | "Sorry, your email has not been verified yet" |
+| `auth.emailAddressVerificationEmail.invalidToken` | "Email verification link is invalid or has expired" |
+| `auth.passwordReset.invalidToken` | "Password reset link is invalid or has expired" |
+
+> **Note:** The message catalog also contains `emails.*.body` text templates, but these are not used. The system reads HTML templates from the `htmlTemplates/` directory instead.
+
+## API Endpoints
+
+### Email-Related Auth Endpoints
+
+| Method | Endpoint | Description | Rate Limit |
+|--------|----------|-------------|------------|
+| `POST` | `/api/auth/signin/local` | User login | 10/15min |
+| `POST` | `/api/auth/send-email-address-verification-email` | Resend verification (auth required) | - |
+| `PUT` | `/api/auth/verify-email` | Verify email token | - |
+| `POST` | `/api/auth/send-password-reset-email` | Send password reset | 5/hour |
+| `PUT` | `/api/auth/password-reset` | Reset password with token | - |
+| `PUT` | `/api/auth/password-update` | Change password (auth required) | - |
+| `GET` | `/api/auth/email-configured` | Check if email is configured | - |
+
+### Rate Limiting
+
+**Source:** `backend/src/middlewares/rateLimiter.ts`
+
+Rate limiters are imported from a centralized middleware:
+
+```javascript
+// backend/src/routes/auth.js
+const {
+  authLimiter: signinLimiter,
+  passwordResetLimiter,
+} = require('../middlewares/rateLimiter');
+
+// Preconfigured limiters in rateLimiter.ts:
+const authLimiter = createRateLimiter({
+  keyPrefix: 'auth',
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 10,
+  message: 'Too many authentication attempts. Please try again later.',
+});
+
+// Self-registration is disabled; no signup limiter is registered.
+
+const passwordResetLimiter = createRateLimiter({
+  keyPrefix: 'password-reset',
+  windowMs: 60 * 60 * 1000, // 1 hour
+  max: 5,
+  message: 'Too many password reset requests. Please try again later.',
+});
+```
+
+Features:
+- Uses centralized in-memory Map with automatic cleanup every 5 minutes
+- Adds standard rate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`)
+- Returns 429 status with JSON response when exceeded
+- Skips rate limiting in development for localhost
+
+## Token Management
+
+### User Model Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `emailVerified` | BOOLEAN | Whether email has been verified |
+| `emailVerificationToken` | TEXT | Token for email verification (40-char hex) |
+| `emailVerificationTokenExpiresAt` | DATE | Token expiration timestamp |
+| `passwordResetToken` | TEXT | Token for password reset (40-char hex) |
+| `passwordResetTokenExpiresAt` | DATE | Token expiration timestamp |
+
+### Token Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Token Lifecycle                                      │
+│                                                                              │
+│  1. Token Generated                                                          │
+│     └── crypto.randomBytes(20).toString('hex')                              │
+│     └── Expiration: Date.now() + 24 hours                                   │
+│                                                                              │
+│  2. Token Stored                                                             │
+│     └── users.emailVerificationToken / passwordResetToken                   │
+│     └── users.emailVerificationTokenExpiresAt / passwordResetTokenExpiresAt │
+│                                                                              │
+│  3. Email Sent                                                               │
+│     └── Link: {host}/verify-email?token={token}                             │
+│     └── Link: {host}/password-reset?token={token}                           │
+│                                                                              │
+│  4. Token Validated                                                          │
+│     └── Check token exists                                                   │
+│     └── Check tokenExpiresAt > Date.now()                                   │
+│                                                                              │
+│  5. Token Consumed                                                           │
+│     └── emailVerified = true (verification)                                 │
+│     └── password updated (reset)                                            │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Email Verification Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      Email Verification Flow                                 │
+│                                                                              │
+│  User                        Backend                         AWS SES        │
+│    │                            │                               │           │
+│    │ POST /api/auth/send-email-address-verification-email        │           │
+│    │───────────────────────────>│                               │           │
+│    │                            │                               │           │
+│    │                            │ Create user                   │           │
+│    │                            │ Generate verification token   │           │
+│    │                            │                               │           │
+│    │                            │ EmailSender.send()            │           │
+│    │                            │──────────────────────────────>│           │
+│    │                            │                               │           │
+│    │                            │<──────────────────────────────│           │
+│    │<───────────────────────────│ 200 OK (JWT token)            │           │
+│    │                            │                               │           │
+│    │                     [Email arrives with verification link]             │
+│    │                            │                               │           │
+│    │ PUT /api/auth/verify-email │                               │           │
+│    │ { token: "..." }           │                               │           │
+│    │───────────────────────────>│                               │           │
+│    │                            │                               │           │
+│    │                            │ Validate token & expiry       │           │
+│    │                            │ Set emailVerified = true      │           │
+│    │                            │                               │           │
+│    │<───────────────────────────│ 200 OK                        │           │
+│    │                            │                               │           │
+│    │      [User can now sign in normally]                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Invitation Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Invitation Flow                                      │
+│                                                                              │
+│  Admin                       Backend                          New User      │
+│    │                            │                               │           │
+│    │ POST /api/users            │                               │           │
+│    │ { email, sendInvite:true } │                               │           │
+│    │───────────────────────────>│                               │           │
+│    │                            │                               │           │
+│    │                            │ Create user record            │           │
+│    │                            │ Generate password reset token │           │
+│    │                            │ Send invitation email ───────>│           │
+│    │                            │                               │           │
+│    │<───────────────────────────│ 200 OK                        │           │
+│    │                            │                               │           │
+│    │                            │           [Email with invitation link]    │
+│    │                            │                               │           │
+│    │                            │       Click link: /password-reset?token=  │
+│    │                            │<──────────────────────────────│           │
+│    │                            │                               │           │
+│    │                            │ PUT /api/auth/password-reset  │           │
+│    │                            │ { token, password }           │           │
+│    │                            │                               │           │
+│    │                            │ Set password                  │           │
+│    │                            │ (Auto-verifies email)         │           │
+│    │                            │                               │           │
+│    │                            │──────────────────────────────>│           │
+│    │                            │ 200 OK - Account ready        │           │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Error Handling
+
+### Validation Errors
+
+| Error Key | Message | HTTP Status |
+|-----------|---------|-------------|
+| `auth.userNotVerified` | "Sorry, your email has not been verified yet" | 400 |
+| `auth.emailAddressVerificationEmail.invalidToken` | "Email verification link is invalid or has expired" | 400 |
+| `auth.emailAddressVerificationEmail.error` | "Email not recognized" | 400 |
+| `auth.passwordReset.invalidToken` | "Password reset link is invalid or has expired" | 400 |
+| `auth.passwordReset.error` | "Email not recognized" | 400 |
+
+### Graceful Degradation
+
+When email is not configured (`EmailSender.isConfigured === false`):
+
+1. **Signup:** Users are automatically marked as verified
+2. **Signin:** Email verification check is bypassed
+3. **Password Reset:** Endpoint returns success but no email is sent
+
+```typescript
+// backend/src/services/auth.ts
+if (!EmailSender.isConfigured) {
+  user.emailVerified = true;  // Auto-verify when email not configured
+}
+```
+
+## File Structure
+
+```
+backend/src/
+├── middlewares/
+│   └── rateLimiter.ts                    # Centralized rate limiting middleware
+└── services/
+    ├── email/
+    │   ├── index.ts                      # EmailSender class
+    │   ├── list/
+    │   │   ├── addressVerification.ts    # Email verification template
+    │   │   ├── invitation.ts             # User invitation template
+    │   │   └── passwordReset.ts          # Password reset template
+    │   └── htmlTemplates/
+    │       ├── addressVerification/
+    │       │   └── emailAddressVerification.html
+    │       ├── invitation/
+    │       │   └── invitationTemplate.html
+    │       └── passwordReset/
+    │           └── passwordResetEmail.html
+    └── notifications/
+        ├── helpers.js                    # getNotification() function
+        ├── list.js                       # Message catalog
+        └── errors/
+            ├── forbidden.js              # ForbiddenError class
+            └── validation.js             # ValidationError class
+```
+
+## Known Considerations
+
+1. **AWS SES Region:** The system is configured for `us-east-1`. For other regions, update `config.email.host`.
+
+2. **Token Expiration:** All tokens expire after 24 hours. This was increased from the original 6 minutes to accommodate email delivery delays.
+
+3. **Rate Limiting:** Uses centralized in-memory rate limiting in `backend/src/middlewares/rateLimiter.ts` (not distributed). Rate limits reset on server restart. Automatic cleanup of expired entries every 5 minutes.
+
+4. **SES Configuration Set:** The `X-SES-CONFIGURATION-SET: flatlogic-app` header enables SES tracking features.
+
+5. **Email Not Configured Mode:** The system gracefully handles missing email configuration by auto-verifying users, useful for development environments.
+
+6. **Invitation vs Password Reset:** Invitations use the same token mechanism as password reset, with a different email template. The link includes `&invitation=true` to indicate the context.
+
+7. **TLS Certificate Validation:** Can be disabled via `EMAIL_TLS_REJECT_UNAUTHORIZED=false` for development environments with self-signed certificates.
diff --git a/documentation/global-ui-controls.md b/documentation/global-ui-controls.md
new file mode 100644
index 0000000..52e542f
--- /dev/null
+++ b/documentation/global-ui-controls.md
@@ -0,0 +1,209 @@
+# Global UI Controls
+
+## Overview
+
+Global UI controls are system-owned presentation buttons for fullscreen, global
+sound mute, and offline mode. They are not regular canvas elements and are not
+stored in `tour_pages.ui_schema_json.elements`.
+
+They behave like runtime chrome:
+- button dimensions use canvas-relative percentages
+- button positions are relative to the visible canvas using `xPercent/yPercent`
+- constructor edit mode renders controls even when hidden
+- controls can be disabled or hidden, but cannot be deleted
+- each control can use custom default and active icons from Assets
+
+## Implementation Files
+
+Backend:
+- `backend/src/db/models/global_ui_control_defaults.js`
+- `backend/src/db/models/project_ui_control_settings.js`
+- `backend/src/db/api/global_ui_control_defaults.ts`
+- `backend/src/db/api/project_ui_control_settings.ts`
+- `backend/src/routes/global_ui_control_defaults.ts`
+- `backend/src/routes/project_ui_control_settings.ts`
+- `backend/src/services/global_ui_control_defaults.ts`
+- `backend/src/services/project_ui_control_settings.ts`
+
+Frontend:
+- `frontend/src/types/uiControls.ts`
+- `frontend/src/components/UiControls/UiControlsSettingsForm.tsx`
+- `frontend/src/components/Runtime/RuntimeControls.tsx`
+- `frontend/src/components/Constructor/ElementEditorPanel.tsx`
+- `frontend/src/stores/global_ui_control_defaults/globalUiControlDefaultsSlice.ts`
+- `frontend/src/stores/project_ui_control_settings/projectUiControlSettingsSlice.ts`
+- `frontend/src/components/RuntimePresentation.tsx`
+- `frontend/src/pages/constructor.tsx`
+- `frontend/src/pages/global-ui-control-defaults.tsx`
+- `frontend/src/pages/global-ui-control-defaults/[controlType].tsx`
+- `frontend/src/pages/project-ui-control-settings.tsx`
+
+## Cascade
+
+Settings resolve field-by-field:
+
+```
+global_ui_control_defaults
+  -> project_ui_control_settings (project + environment)
+  -> tour_pages.global_ui_controls_settings_json
+```
+
+Missing fields inherit from the previous cascade level: page settings override
+project settings, project settings override global defaults, and frontend
+hardcoded defaults are only a safety fallback.
+
+## Data Shape
+
+Each control (`fullscreen`, `sound`, `offline`) supports:
+
+| Field | Purpose |
+|-------|---------|
+| `enabled` | Disable action while keeping the control selectable in edit mode |
+| `hidden` | Hide in runtime/preview; still render as ghost in constructor edit mode |
+| `xPercent`, `yPercent` | Canvas-relative position |
+| `anchor` | Which button point is placed at the coordinate |
+| `buttonSizePercent`, `iconSizePercent`, `borderRadiusPercent` | Canvas-width-relative dimensions |
+| `defaultIconUrl`, `activeIconUrl` | Optional custom asset URL/storage key per state |
+| `defaultBackgroundColor`, `activeBackgroundColor` | Button background color per state |
+| `defaultBorderColor`, `activeBorderColor` | Button border color per state |
+| `hoverBackgroundColor`, `color` | Shared hover background and icon color |
+| `opacity`, `boxShadow`, `zIndex`, `order` | Presentation and initial ordering |
+
+Active state means downloaded/offline for the offline button, muted for the
+sound button, and fullscreen for the fullscreen button.
+
+When runtime is embedded in an iframe, the fullscreen control first tries the
+browser Fullscreen API for the presentation document, then tries to fullscreen
+the embedding iframe when same-origin access is available. For cross-origin
+wrappers it posts `tour-builder:request-fullscreen` to `window.parent`; exit
+attempts post `tour-builder:exit-fullscreen`.
+
+```html
+<iframe id="tour-frame" src="https://example.com/p/project" allow="fullscreen" allowfullscreen></iframe>
+<script>
+  window.addEventListener('message', async (event) => {
+    const frame = document.getElementById('tour-frame');
+
+    if (event.data?.type === 'tour-builder:request-fullscreen') {
+      await frame?.requestFullscreen?.();
+    }
+
+    if (event.data?.type === 'tour-builder:exit-fullscreen' && document.fullscreenElement) {
+      await document.exitFullscreen();
+    }
+  });
+</script>
+```
+
+Dimensions are stored as percentages of canvas width. `buttonSizePercent` and
+`iconSizePercent` resolve from the displayed canvas width. Vertical bounds use
+the canvas aspect ratio, so buttons remain fully inside the visible canvas for
+non-16:9 projects as well.
+
+Default global values:
+
+| Control | X | Y | Size | Icon | Radius | Order |
+|---------|---|---|------|------|--------|-------|
+| `offline` | `89.5` | `6` | `2.6` | `1.35` | `0.42` | `1` |
+| `fullscreen` | `92.75` | `6` | `2.6` | `1.35` | `0.42` | `2` |
+| `sound` | `96` | `6` | `2.6` | `1.35` | `0.42` | `3` |
+
+## APIs
+
+- `GET /api/global-ui-control-defaults`
+- `PUT /api/global-ui-control-defaults/:id`
+- `GET /api/project-ui-control-settings/project/:projectId/env/:environment`
+- `PUT /api/project-ui-control-settings/project/:projectId/env/:environment`
+- `DELETE /api/project-ui-control-settings/project/:projectId/env/:environment`
+
+Production project settings reads follow the same public/private access rules
+as runtime transition settings. Dev/stage and writes require JWT.
+
+`GET /api/global-ui-control-defaults` is public-readable for runtime. Updates
+require JWT and `UPDATE_PAGE_ELEMENTS`; these settings are authored with the
+same permission family as element defaults. Project-level `production` reads
+are public only for public production presentations; private production
+presentations require JWT and presentation access.
+
+Project override writes require `UPDATE_PAGE_ELEMENTS`. The project
+environment reset endpoint is implemented as `DELETE` because it removes the
+override row, but authorization treats it as an update operation: it also
+requires `UPDATE_PAGE_ELEMENTS`, not `DELETE_PAGE_ELEMENTS`.
+
+## Constructor Behavior
+
+Constructor renders controls through `RuntimeControls` with `editMode=true`.
+Selecting a system control opens the element editor in system-control mode.
+
+System controls:
+- can be dragged to update `xPercent/yPercent`
+- can be edited with coordinate inputs
+- can choose separate default and active custom icons
+- can edit default/active background colors and border colors
+- can edit hidden/disabled state, order, z-index, opacity, shadow, size, radius,
+  and anchor
+- cannot be removed, copied, or pasted
+
+Constructor system-control opacity is edited as a clamped percentage from `0`
+to `100` and converted to the stored runtime opacity number from `0` to `1`.
+
+Constructor edit mode blocks runtime actions. Clicking or dragging system
+controls does not toggle fullscreen, sound, or offline mode. Hidden controls are
+rendered as ghost controls so authors can reselect and unhide them.
+
+## Admin Editing UI
+
+Global defaults are listed at `/global-ui-control-defaults` and edited per
+control:
+- `/global-ui-control-defaults/offline`
+- `/global-ui-control-defaults/fullscreen`
+- `/global-ui-control-defaults/sound`
+
+Project-level overrides are edited from
+`/project-ui-control-settings?projectId=...`.
+
+The per-control global pages and project page use `UiControlsSettingsForm`, a
+typed editor with the same tab model used by element defaults:
+- **General Settings**: enabled/hidden state, canvas-relative position, anchor,
+  order, and default/active icon URLs
+- **CSS Styles**: button/icon sizing, radius, icon color, background colors,
+  and border colors
+- **Effects**: opacity, z-index, and box shadow
+
+Opacity inputs in the constructor/editor UI are percentage-based for authors;
+stored `settings_json.opacity` remains a numeric CSS opacity value.
+
+Project settings can be cleared with **Use Global Defaults**, which deletes the
+project/environment override so the project inherits global defaults again.
+
+## Publishing
+
+`project_ui_control_settings` is environment-aware and is copied by the publish
+workflow:
+
+```
+dev -> stage -> production
+```
+
+Page-level overrides live on `tour_pages` and are copied with page records.
+Project clone copies project UI-control settings for each environment, and page
+duplication copies page-level `global_ui_controls_settings_json`.
+
+## Migrations
+
+- `20260628000001-create-ui-control-settings.js` creates the two DB models,
+  adds `tour_pages.global_ui_controls_settings_json`, creates the project/env
+  unique index, and seeds the initial global defaults.
+- `20260628000005-snapshot-existing-project-ui-controls.js` snapshots
+  project-level settings for existing projects that do not already have
+  project UI-control overrides.
+
+## Existing Projects
+
+Migration `20260628000005-snapshot-existing-project-ui-controls.js` snapshots
+the previous runtime chrome layout into project-level settings for existing
+projects in `dev`, `stage`, and `production` when no project UI-control override
+already exists. The snapshot keeps the old top-right grouped placement offsets
+and previous runtime z-index, but stores dimensions with the same
+canvas-relative defaults used by new projects (`2.6%` button size, `1.35%` icon
+size, `0.42%` radius).
diff --git a/documentation/offline-pwa-mode.md b/documentation/offline-pwa-mode.md
new file mode 100644
index 0000000..3626218
--- /dev/null
+++ b/documentation/offline-pwa-mode.md
@@ -0,0 +1,1540 @@
+# Offline PWA Mode - E2E Documentation
+
+## Overview
+
+The Tour Builder Platform implements a sophisticated Progressive Web App (PWA) system enabling complete offline functionality. The system combines Service Workers, Cache API, and IndexedDB to provide seamless offline tour experiences with intelligent caching, download resume capability, and network adaptation.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Service Worker Layer                         │
+│  Serwist (sw.ts) │ Precaching │ Runtime Caching │ Range Requests│
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                      Storage Layer                               │
+│  Cache API (< 5MB) │ IndexedDB (≥ 5MB) │ StorageManager         │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Download Layer                               │
+│  DownloadManager │ DownloadEventBus │ Queue Persistence         │
+│  assetUrl (presigned URLs + proxy fallback)                     │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                 Asset Cache Service Layer                        │
+│  AssetCacheService │ assetDiscovery │ discoverProjectAssets     │
+│  Unified asset discovery for online preload and offline mode    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Hook Layer                                   │
+│  usePreloadOrchestrator │ usePageSwitch │ useNeighborGraph      │
+│  useNetworkAware │ useOfflineMode │ useStorageQuota             │
+│  usePreloadProgress │ usePWAPreload                              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     UI Components                                │
+│  OfflineToggle │ OfflineStatusIndicator │ StorageUsageDisplay   │
+│  DownloadProgressPanel                                           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Service Worker (Serwist)
+
+### Configuration
+
+Location: `frontend/src/sw.ts`
+
+Built with **Serwist** (modern Workbox successor):
+
+```javascript
+// next.config.mjs
+{
+  swSrc: 'src/sw.ts',
+  swDest: 'public/sw.js',
+  disable: process.env.NODE_ENV === 'development',
+  maximumFileSizeToCacheInBytes: 5 * 1024 * 1024
+}
+```
+
+The raised precache size limit keeps the main `_app` chunk in the Serwist
+precache. `next.config.mjs` also sets `outputFileTracingRoot` to the frontend
+directory so Next.js does not infer a parent workspace root when unrelated
+lockfiles exist above the project.
+
+### Caching Strategies
+
+| Resource Type | Strategy | Cache Name |
+|--------------|----------|------------|
+| Build assets | Precache | `serwist-precache-v2` |
+| Images, fonts, CSS, JS | CacheFirst + cacheKeyWillBeUsed | `tour-builder-assets-v1` |
+| Videos | CacheFirst + Range + cacheKeyWillBeUsed | `tour-builder-assets-v1` |
+| API responses | NetworkFirst | `api-cache` |
+| Audio files | CacheFirst + cacheKeyWillBeUsed | `tour-builder-assets-v1` |
+
+### Unified Cache Keys (cacheKeyWillBeUsed Plugin)
+
+All asset handlers use the `cacheKeyWillBeUsed` plugin to normalize URLs to storage keys. This ensures that:
+- Preload (DownloadManager) stores assets with storage keys: `assets/project-id/file.jpg`
+- Browser loads (SW interception) also use storage keys for cache lookup and storage
+- Cache hits occur regardless of presigned URL signature changes
+
+```typescript
+// Applied to static, video, audio, and dynamic asset handlers
+cacheKeyWillBeUsed: async ({ request, mode }) => {
+  const storagePath = extractStoragePathFromUrl(request.url);
+  if (storagePath) {
+    console.log(`[SW] Using storagePath for ${mode}:`, storagePath.slice(-40));
+    return new Request(storagePath);
+  }
+  return request;
+}
+```
+
+### Cacheable Extensions
+
+```
+Images: .png, .jpg, .jpeg, .gif, .webp, .svg, .ico
+Video:  .mp4, .webm, .mov
+Audio:  .mp3, .wav, .ogg, .m4a
+Fonts:  .woff, .woff2, .ttf, .eot
+Code:   .css, .js
+```
+
+### Range Request Support
+
+Enables video seeking in cached content via Serwist plugin:
+
+```typescript
+// sw.ts - Video caching with Range support using Serwist plugin
+{
+  matcher: ({ request }) => isVideoRequest(request),
+  handler: new CacheFirst({
+    cacheName: OFFLINE_CONFIG.cacheNames.assets,
+    plugins: [
+      {
+        // Handle range requests for video seeking
+        cachedResponseWillBeUsed: async ({ cachedResponse, request }) => {
+          if (!cachedResponse) return null;
+
+          const rangeHeader = request.headers.get('range');
+          if (!rangeHeader) return cachedResponse;
+
+          // Parse range header
+          const match = rangeHeader.match(/bytes=(\d+)-(\d*)/);
+          if (!match) return cachedResponse;
+
+          const start = parseInt(match[1], 10);
+          const end = match[2] ? parseInt(match[2], 10) : undefined;
+
+          // Get the full response body
+          const blob = await cachedResponse.blob();
+          const slicedBlob =
+            end !== undefined
+              ? blob.slice(start, end + 1)
+              : blob.slice(start);
+
+          // Return partial content
+          return new Response(slicedBlob, {
+            status: 206,
+            statusText: 'Partial Content',
+            headers: {
+              'Content-Type':
+                cachedResponse.headers.get('Content-Type') || 'video/mp4',
+              'Content-Length': String(slicedBlob.size),
+              'Content-Range': `bytes ${start}-${end !== undefined ? end : blob.size - 1}/${blob.size}`,
+              'Accept-Ranges': 'bytes',
+            },
+          });
+        },
+        cacheWillUpdate: async ({ response }) => {
+          if (response && response.status === 200) {
+            return response;
+          }
+          return null;
+        },
+      },
+    ],
+  }),
+},
+```
+
+### Message API
+
+Service worker receives commands from main thread:
+
+| Message | Payload | Description |
+|---------|---------|-------------|
+| `CACHE_ASSETS` | `{ urls: string[] }` | Cache specific asset URLs |
+| `CACHE_VIDEO_CHUNK` | `{ url, chunk, contentType }` | Cache video chunks with streaming |
+| `CLEAR_CACHE` | - | Clear all dynamic caches |
+| `GET_CACHE_STATUS` | - | Query cache status |
+| `SKIP_WAITING` | - | Force immediate activation |
+
+```typescript
+// Main thread → Service Worker
+navigator.serviceWorker.controller.postMessage({
+  type: 'CACHE_ASSETS',
+  payload: { urls: ['https://example.com/video.mp4'] }
+});
+
+// Service Worker → Main thread (response to GET_CACHE_STATUS)
+// { type: 'CACHE_STATUS', payload: { cachedCount: number, urls: string[] } }
+```
+
+### Lifecycle
+
+```
+1. Registration → Next.js/Serwist auto-registers (production)
+2. Installation → Caches all precache entries (build assets)
+3. Activation  → Deletes old cache versions, claims clients
+4. Fetch       → Intercepts requests, applies strategies
+5. Update      → Checks for updates every 60 minutes
+```
+
+---
+
+## Cache Organization
+
+### Named Caches
+
+```typescript
+// frontend/src/config/offline.config.ts
+cacheNames: {
+  static: 'tour-builder-static-v1',   // Precached build assets
+  dynamic: 'tour-builder-dynamic-v1', // Runtime API responses (note: SW uses 'api-cache')
+  assets: 'tour-builder-assets-v1',   // Project assets (used by SW and preloading)
+}
+```
+
+**Note**: The actual API cache in the Service Worker is `api-cache`, not `tour-builder-dynamic-v1`. The `dynamic` config key is reserved for future use.
+
+### Cache Invalidation
+
+Version bump clears old caches on SW activation:
+
+```
+tour-builder-static-v1 → tour-builder-static-v2
+                         ↓
+        Old v1 cache automatically deleted
+```
+
+---
+
+## Dual Storage Strategy
+
+### Storage Decision
+
+```
+┌─────────────────────────────────────────┐
+│           File Size Check               │
+└─────────────────────────────────────────┘
+                  │
+        ┌─────────┴─────────┐
+        │                   │
+        ▼                   ▼
+   Size < 5MB          Size ≥ 5MB
+        │                   │
+        ▼                   ▼
+┌───────────────┐   ┌───────────────┐
+│   Cache API   │   │   IndexedDB   │
+│  (Fast, SW)   │   │ (Large files) │
+└───────────────┘   └───────────────┘
+```
+
+### Why Dual Storage?
+
+| Storage | Pros | Cons |
+|---------|------|------|
+| **Cache API** | Fast, SW integration, simple API | Size limits, no metadata |
+| **IndexedDB** | Large files, rich metadata, queries | Slower, more complex |
+
+### StorageManager
+
+Location: `frontend/src/lib/offline/StorageManager.ts`
+
+```typescript
+class StorageManager {
+  // Storage quota check (returns StorageQuotaInfo with canStore function)
+  static async getStorageQuota(): Promise<StorageQuotaInfo>;
+
+  // Request persistent storage (won't be cleared by browser)
+  static async requestPersistentStorage(): Promise<boolean>;
+
+  // Determine storage location (5MB threshold)
+  static shouldUseIndexedDB(sizeBytes: number): boolean {
+    return sizeBytes >= OFFLINE_CONFIG.storage.indexedDbMinSize;
+  }
+
+  // Store asset (auto-selects Cache API or IndexedDB based on size)
+  static async storeAsset(url: string, blob: Blob, metadata: AssetMetadata): Promise<void>;
+
+  // Retrieve asset (checks IndexedDB first, then Cache API)
+  static async getAsset(url: string): Promise<Blob | null>;
+
+  // Check if asset exists (checks both storages)
+  static async hasAsset(url: string): Promise<boolean>;
+
+  // Delete asset from both storages
+  static async deleteAsset(url: string, assetId?: string): Promise<void>;
+
+  // Bulk delete for project
+  static async deleteProjectAssets(projectId: string): Promise<void>;
+
+  // Send URLs to SW for caching
+  static async cacheViaServiceWorker(urls: string[]): Promise<void>;
+
+  // Get SW cache status
+  static async getServiceWorkerCacheStatus(): Promise<{ cachedCount: number; urls: string[] }>;
+
+  // Get total storage used
+  static async getTotalStorageUsed(): Promise<number>;
+
+  // Clear all offline storage
+  static async clearAll(): Promise<void>;
+}
+```
+
+---
+
+## IndexedDB Schema
+
+### Database: `TourBuilderOffline` (v1)
+
+Location: `frontend/src/lib/offlineDb/schema.ts`
+
+**Built with Dexie.js:**
+
+```typescript
+import Dexie, { type EntityTable } from 'dexie';
+
+class OfflineDatabase extends Dexie {
+  assets!: EntityTable<OfflineAsset, 'id'>;
+  projects!: EntityTable<OfflineProject, 'id'>;
+  downloadQueue!: EntityTable<DownloadQueueItem, 'id'>;
+
+  constructor() {
+    super(OFFLINE_CONFIG.dbName); // 'TourBuilderOffline'
+
+    this.version(OFFLINE_CONFIG.dbVersion).stores({
+      // Index definitions (comma-separated indexed fields)
+      assets: 'id, projectId, url, variantType, assetType, downloadedAt',
+      projects: 'id, slug, status, lastSyncedAt',
+      downloadQueue: 'id, projectId, status, priority, addedAt',
+    });
+  }
+}
+```
+
+### Assets Table
+
+```typescript
+interface OfflineAsset {
+  id: string;
+  projectId: string;
+  url: string;
+  filename: string;
+  variantType: AssetVariantType;
+  assetType: AssetType;
+  mimeType: string;
+  sizeBytes: number;
+  blob: Blob;              // Actual file data
+  downloadedAt: number;    // Timestamp
+}
+```
+
+### Projects Table
+
+```typescript
+interface OfflineProject {
+  id: string;
+  slug: string;
+  name: string;             // Project display name
+  status: ProjectOfflineStatus;
+  totalAssets: number;
+  downloadedAssets: number;
+  totalSizeBytes: number;
+  downloadedSizeBytes: number;
+  lastSyncedAt?: number;    // Optional timestamp
+  version?: string;         // Manifest version for update detection
+}
+
+type ProjectOfflineStatus =
+  | 'not_downloaded'
+  | 'downloading'
+  | 'downloaded'
+  | 'outdated'
+  | 'error';
+```
+
+### Download Queue Table
+
+```typescript
+interface DownloadQueueItem {
+  id: string;
+  projectId: string;
+  assetId: string;
+  url: string;
+  filename: string;
+  status: PreloadJobStatus;  // 'queued' | 'downloading' | 'completed' | 'error' | 'paused'
+  priority: number;
+  retryCount: number;
+  bytesLoaded: number;
+  totalBytes: number;
+  addedAt: number;
+  lastAttemptAt?: number;
+  error?: string;
+}
+```
+
+### OfflineDbManager
+
+Location: `frontend/src/lib/offlineDb/OfflineDbManager.ts` (~342 LOC)
+
+```typescript
+class OfflineDbManager {
+  // Asset operations
+  static async storeAsset(asset: OfflineAsset): Promise<void>;
+  static async getAsset(id: string): Promise<OfflineAsset | undefined>;
+  static async getAssetByUrl(url: string): Promise<OfflineAsset | undefined>;
+  static async getProjectAssets(projectId: string): Promise<OfflineAsset[]>;
+  static async deleteAsset(id: string): Promise<void>;
+  static async deleteProjectAssets(projectId: string): Promise<number>;
+  static async hasAsset(id: string): Promise<boolean>;
+  static async hasAssetByUrl(url: string): Promise<boolean>;
+  static async getTotalAssetsSize(): Promise<number>;
+  static async getProjectAssetsSize(projectId: string): Promise<number>;
+
+  // Project tracking
+  static async upsertProject(project: OfflineProject): Promise<void>;
+  static async getProject(id: string): Promise<OfflineProject | undefined>;
+  static async getProjectBySlug(slug: string): Promise<OfflineProject | undefined>;
+  static async getAllProjects(): Promise<OfflineProject[]>;
+  static async updateProjectStatus(id: string, status: ProjectOfflineStatus): Promise<void>;
+  static async updateProjectProgress(id: string, downloadedAssets: number, downloadedSizeBytes: number): Promise<void>;
+  static async deleteProject(id: string): Promise<void>;
+
+  // Queue management
+  static async addToQueue(item: DownloadQueueItem): Promise<void>;
+  static async getQueueItem(id: string): Promise<DownloadQueueItem | undefined>;
+  static async getProjectQueue(projectId: string): Promise<DownloadQueueItem[]>;
+  static async getPendingQueue(): Promise<DownloadQueueItem[]>;
+  static async updateQueueStatus(id: string, status: PreloadJobStatus, error?: string): Promise<void>;
+  static async updateQueueProgress(id: string, bytesLoaded: number, totalBytes: number): Promise<void>;
+  static async incrementRetry(id: string): Promise<number>;
+  static async removeFromQueue(id: string): Promise<void>;
+  static async clearProjectQueue(projectId: string): Promise<number>;
+  static async clearQueue(): Promise<void>;
+  static async resetFailedItems(projectId?: string): Promise<number>;
+
+  // Utility
+  static async clearAll(): Promise<void>;
+  static async getStats(): Promise<{
+    projectCount: number;
+    assetCount: number;
+    queueCount: number;
+    totalSizeBytes: number;
+  }>;
+}
+```
+
+---
+
+## Download Manager
+
+Location: `frontend/src/lib/offline/DownloadManager.ts`
+
+### Features
+
+- **Priority Queue** - Downloads sorted by importance
+- **Concurrent Downloads** - Configurable max (default: 3)
+- **Streaming Progress** - Uses `response.body.getReader()`
+- **Retry Logic** - 3 retries with linear backoff
+- **Queue Persistence** - Resumes after page reload via IndexedDB
+- **Pause/Resume** - Pause all or individual downloads via AbortController
+- **Cancellation** - Cancel downloads by project or individually
+- **Presigned URL → Proxy Fallback** - Automatic fallback when S3 presigned URLs fail (CORS)
+
+### Priority Calculation
+
+```typescript
+priority = assetTypePriority + variantPriority
+
+// Asset type weights (PRELOAD_CONFIG.priority.assetType)
+transition: 150  // Highest - needed immediately on navigation click
+image: 100
+audio: 50
+video: 30
+
+// Variant weights (PRELOAD_CONFIG.priority.variant)
+thumbnail: 50
+preview: 40
+webp: 35
+mp4_low: 20
+mp4_high: 10
+original: 5
+```
+
+### Download Flow
+
+```
+┌─────────────────────────────────────────┐
+│  1. Add assets to queue                 │
+│     └── downloadManager.addJob(params)  │
+└─────────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────┐
+│  2. Persist to IndexedDB                │
+│     └── Resume capability on reload     │
+└─────────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────┐
+│  3. Sort by priority                    │
+│     └── Higher priority = download first│
+└─────────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────┐
+│  4. Process queue (max 3 concurrent)    │
+│     └── fetch() with AbortController    │
+└─────────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────┐
+│  5. Stream response body                │
+│     └── response.body.getReader()       │
+│     └── Track bytesLoaded / totalBytes  │
+│     └── Emit progress events            │
+└─────────────────────────────────────────┘
+                  │
+           ┌──────┴──────┐
+           ▼             ▼
+┌──────────────────┐  ┌─────────────────────────┐
+│  Download OK     │  │  Download FAILED        │
+│                  │  │  (e.g., CORS error)     │
+└────────┬─────────┘  └───────────┬─────────────┘
+         │                        │
+         │                        ▼
+         │            ┌─────────────────────────┐
+         │            │  6a. Presigned URL?     │
+         │            │  → Retry with proxy URL │
+         │            │  /api/file/download?... │
+         │            └───────────┬─────────────┘
+         │                        │
+         ▼                        ▼
+┌─────────────────────────────────────────┐
+│  7. Store in appropriate storage        │
+│     └── < 5MB → Cache API               │
+│     └── ≥ 5MB → IndexedDB               │
+│     └── With isPartial flag if partial  │
+└─────────────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────┐
+│  8. Emit completion event               │
+│     └── emitComplete({ storageKey })    │
+└─────────────────────────────────────────┘
+```
+
+### Retry Configuration
+
+```typescript
+// From PRELOAD_CONFIG
+retry: {
+  maxRetries: 3,
+  retryDelayMs: 1000,  // Delay before retry
+}
+
+// Linear backoff: retryDelayMs * retryCount
+// 1s → 2s → 3s
+```
+
+### Resume Capability
+
+Queue state persisted in IndexedDB:
+
+```typescript
+// On page load
+await downloadManager.restoreQueue();
+
+// Restores pending/paused items from downloadQueue table
+// Re-adds to in-memory queue sorted by priority
+// Continues processing automatically
+```
+
+### API
+
+```typescript
+const downloadManager = new DownloadManagerClass();
+
+// Add job
+await downloadManager.addJob({
+  assetId: string;
+  projectId: string;
+  url: string;
+  filename: string;
+  variantType: AssetVariantType;
+  assetType: AssetType;
+  priority?: number;  // Auto-calculated if not provided
+});
+
+// Control
+downloadManager.pauseAll();
+downloadManager.resumeAll();
+downloadManager.cancelJob(jobId: string);
+downloadManager.cancelProjectDownloads(projectId: string);
+downloadManager.clearQueue();
+
+// Status
+downloadManager.getStatus(); // { queueLength, activeCount, isPaused }
+
+// Restore
+await downloadManager.restoreQueue();
+```
+
+---
+
+## S3 Presigned URL Integration
+
+For S3 storage, the preload system uses presigned URLs for direct downloads, bypassing the backend proxy.
+
+### Flow
+
+```
+1. Batch fetch presigned URLs
+   └── POST /api/file/presign { urls: [...] }
+
+2. Download directly from S3
+   └── fetch(presignedUrl) with progress tracking
+
+3. Store in Cache API (dual key)
+   └── caches.put(downloadUrl, blob)     // By presigned URL
+   └── caches.put(storageKey, blob)      // By canonical path (e.g., "assets/vid.mp4")
+
+4. Create blob URL
+   └── URL.createObjectURL(blob)
+
+5. Pre-decode (images only)
+   └── new Image().decode() on blob URL
+
+6. Store ready blob URL (dual key)
+   └── readyBlobUrlsRef.set(downloadUrl, blobUrl)
+   └── readyBlobUrlsRef.set(storageKey, blobUrl)  // Enables lookup after URL change
+```
+
+**Storage Key Mapping:**
+Assets are stored under both download URL AND storage key (canonical path). This ensures cache hits even when presigned URLs change signatures or after page refresh:
+
+| Scenario | Lookup Key | Result |
+|----------|------------|--------|
+| Same session | `storageKey` | ✅ Instant from readyBlobUrlsRef |
+| After URL regeneration | `storageKey` | ✅ Instant (signature doesn't matter) |
+| After page refresh | `storageKey` | ✅ From Cache API |
+
+### Key Functions
+
+| Function | Source | Purpose |
+|----------|--------|---------|
+| `queuePresignedUrls()` | `lib/assetUrl.ts` | Batch queue URLs for presigning |
+| `flushPresignedUrlQueue()` | `lib/assetUrl.ts` | Fetch queued presigned URLs |
+| `resolveAssetPlaybackUrl()` | `lib/assetUrl.ts` | Resolve URL with presigned cache |
+| `getReadyBlobUrl()` | `usePreloadOrchestrator` | O(1) instant lookup for pre-decoded blob URL |
+| `getCachedBlobUrl()` | `usePreloadOrchestrator` | Async fallback - creates blob URL from Cache API |
+
+### Presigned URL Expiry
+
+- URLs expire after 1 hour (3600 seconds)
+- Frontend caches with 1-hour TTL, refreshes 5 minutes before expiry
+- On CORS failure, automatically falls back to backend proxy (`/api/file/download`)
+
+---
+
+## Download Event Bus
+
+Location: `frontend/src/lib/offline/DownloadEventBus.ts`
+
+Browser-native EventEmitter (no Socket.IO dependency):
+
+### Events
+
+| Event | Payload Interface |
+|-------|-------------------|
+| `asset-preload-start` | `PreloadStartEvent` |
+| `asset-preload-progress` | `PreloadProgressEvent` |
+| `asset-preload-complete` | `PreloadCompleteEvent` |
+| `asset-preload-error` | `PreloadErrorEvent` |
+| `project-download-progress` | `ProjectDownloadProgressEvent` |
+| `project-download-complete` | `ProjectDownloadCompleteEvent` |
+| `queue-update` | `void` (no payload) |
+
+### Event Payloads
+
+```typescript
+interface PreloadStartEvent {
+  jobId: string;
+  assetId: string;
+  url: string;
+}
+
+interface PreloadProgressEvent {
+  jobId: string;
+  progress: number;        // 0-100
+  bytesLoaded: number;
+  totalBytes: number;
+}
+
+interface PreloadCompleteEvent {
+  jobId: string;
+  assetId: string;
+  storageKey: string;  // Canonical storage key for cache lookup
+}
+
+interface PreloadErrorEvent {
+  jobId: string;
+  assetId: string;
+  error: string;
+}
+
+interface ProjectDownloadProgressEvent {
+  projectId: string;
+  progress: number;           // 0-100
+  downloadedAssets: number;
+  totalAssets: number;
+  downloadedBytes: number;
+  totalBytes: number;
+}
+
+interface ProjectDownloadCompleteEvent {
+  projectId: string;
+}
+```
+
+### Usage
+
+```typescript
+import { downloadEventBus } from '@/lib/offline/DownloadEventBus';
+import { OFFLINE_CONFIG } from '@/config/offline.config';
+
+// Subscribe to events
+const unsubscribe = downloadEventBus.on(
+  OFFLINE_CONFIG.events.preloadProgress,  // 'asset-preload-progress'
+  (event: PreloadProgressEvent) => {
+    console.log(`Downloaded ${event.progress}%`);
+    updateProgressUI(event.progress);
+  }
+);
+
+// Unsubscribe when done
+unsubscribe();
+
+// Or manually unsubscribe
+downloadEventBus.off(OFFLINE_CONFIG.events.preloadProgress, handler);
+
+// One-time subscription
+downloadEventBus.once(OFFLINE_CONFIG.events.preloadComplete, handler);
+
+// Remove all listeners
+downloadEventBus.removeAllListeners();
+```
+
+### Convenience Methods
+
+```typescript
+// Pre-built emit methods on downloadEventBus
+downloadEventBus.emitPreloadStart(data: PreloadStartEvent);
+downloadEventBus.emitPreloadProgress(data: PreloadProgressEvent);
+downloadEventBus.emitPreloadComplete(data: PreloadCompleteEvent);
+downloadEventBus.emitPreloadError(data: PreloadErrorEvent);
+downloadEventBus.emitProjectProgress(data: ProjectDownloadProgressEvent);
+downloadEventBus.emitProjectComplete(data: ProjectDownloadCompleteEvent);
+downloadEventBus.emitQueueUpdate();
+```
+
+---
+
+## Hooks
+
+### useOfflineMode
+
+Location: `frontend/src/hooks/useOfflineMode.ts`
+
+Orchestrates offline mode for a specific project. Uses **frontend asset discovery** (same as online preloading) - no backend manifest dependency.
+
+```typescript
+interface UseOfflineModeOptions {
+  projectId: string | null;
+  projectSlug?: string;
+  projectName?: string;
+  /** Pages data for frontend asset discovery (required for offline download) */
+  pages?: PreloadPage[];
+  enabled?: boolean;
+}
+
+interface UseOfflineModeResult {
+  // Status
+  isOfflineCapable: boolean;     // SW + caches supported
+  isDownloaded: boolean;         // status === 'downloaded'
+  isDownloading: boolean;        // status === 'downloading' && !isPaused
+  status: ProjectOfflineStatus;
+  progress: number;              // 0-100
+  downloadedAssets: number;
+  totalAssets: number;
+  downloadedBytes: number;
+  totalBytes: number;
+  error: string | null;
+
+  // Actions
+  startDownload: () => Promise<void>;   // Discover assets from pages, queue downloads
+  pauseDownload: () => void;
+  resumeDownload: () => void;
+  cancelDownload: () => void;
+  deleteOfflineData: () => Promise<void>;
+  checkForUpdates: () => Promise<boolean>;
+
+  // Info
+  projectInfo: OfflineProject | null;
+  estimatedSize: number;
+  formatSize: (bytes: number) => string;
+}
+
+// Usage
+const {
+  isDownloaded,
+  isDownloading,
+  progress,
+  startDownload,
+  deleteOfflineData,
+  formatSize,
+  estimatedSize,
+} = useOfflineMode({
+  projectId: '123',
+  projectSlug: 'my-tour',
+  projectName: 'My Tour',
+  pages, // Required: pages data for asset discovery
+});
+```
+
+### useStorageQuota
+
+Location: `frontend/src/hooks/useStorageQuota.ts`
+
+Monitors storage quota and usage:
+
+```typescript
+interface UseStorageQuotaResult extends StorageQuotaInfo {
+  isLoading: boolean;
+  error: string | null;
+  refresh: () => Promise<void>;
+  requestPersistence: () => Promise<boolean>;
+  isPersisted: boolean;
+  isWarning: boolean;   // percentUsed >= 80%
+  isCritical: boolean;  // percentUsed >= 95%
+  formatSize: (bytes: number) => string;
+}
+
+// Usage
+const {
+  usage,
+  quota,
+  percentUsed,
+  available,
+  canStore,
+  isWarning,
+  isCritical,
+  isPersisted,
+  requestPersistence,
+  formatSize,
+} = useStorageQuota();
+
+// Check if we can store 100MB
+if (canStore(100 * 1024 * 1024)) {
+  // Proceed with download
+}
+```
+
+### useNetworkAware
+
+Location: `frontend/src/hooks/useNetworkAware.ts`
+
+Network detection and adaptive behavior:
+
+```typescript
+interface NetworkInfo {
+  isOnline: boolean;
+  effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
+  downlink?: number;      // Mbps
+  rtt?: number;           // Round-trip time (ms)
+  saveData?: boolean;     // Data saver mode
+}
+
+interface UseNetworkAwareResult {
+  networkInfo: NetworkInfo;
+  shouldPreloadAggressively: boolean;  // 4g or downlink >= 5Mbps
+  preferLowQuality: boolean;           // slow-2g, 2g, or saveData
+  recommendedConcurrency: number;      // 1-3 based on connection
+  suggestOfflineMode: boolean;         // Poor connection detected
+}
+
+// Usage
+const {
+  networkInfo,
+  shouldPreloadAggressively,
+  preferLowQuality,
+  recommendedConcurrency,
+} = useNetworkAware();
+
+if (shouldPreloadAggressively) {
+  // Preload neighbor pages
+}
+```
+
+### Concurrency Adaptation
+
+| Connection | Concurrent Downloads |
+|------------|---------------------|
+| 4g / Good | 3 |
+| 3g | 2 |
+| 2g / Slow | 1 |
+| Save-Data | 1 |
+
+---
+
+## UI Components
+
+Location: `frontend/src/components/Offline/`
+
+### OfflineToggle
+
+Button component for toggling offline mode on a project:
+
+```typescript
+interface OfflineToggleProps {
+  projectId: string | null;
+  projectSlug?: string;
+  projectName?: string;
+  /** Pages data for frontend asset discovery (required for offline download) */
+  pages?: PreloadPage[];
+  className?: string;
+  showLabel?: boolean;     // Default: true
+  size?: 'small' | 'medium' | 'large';  // Default: 'medium'
+}
+
+// Usage
+<OfflineToggle
+  projectId={project.id}
+  projectSlug={project.slug}
+  projectName={project.name}
+  pages={filteredPages}  // Required: pages for asset discovery
+  showLabel={true}
+  size="medium"
+/>
+```
+
+Features:
+- Shows download status with icons (cloud download, cloud check, cloud off)
+- Displays size estimate before download
+- Shows progress percentage during download
+- Downloaded state switches the same runtime control into its active/remove
+  state; deleting offline data uses the active offline button with confirmation
+- Storage quota warnings
+- Confirmation dialogs for deletion
+
+### OfflineStatusIndicator
+
+Displays current offline/online status with visual indicator.
+
+### StorageUsageDisplay
+
+Shows storage quota usage with progress bar and statistics.
+
+### DownloadProgressPanel
+
+Panel showing active downloads with individual progress bars and controls.
+
+---
+
+## Frontend Asset Discovery
+
+### Overview
+
+Asset discovery is handled entirely in the frontend using the same logic for both online preloading and offline downloads. This ensures consistency and eliminates backend dependencies.
+
+Location: `frontend/src/lib/assetCache/`
+
+### Key Components
+
+| File | Purpose |
+|------|---------|
+| `AssetCacheService.ts` | Unified entry point for asset caching |
+| `assetDiscovery.ts` | Shared asset extraction logic |
+| `index.ts` | Module exports |
+
+### Asset Discovery Functions
+
+```typescript
+// Discover all assets for a project (offline download)
+discoverProjectAssets(
+  pages: PreloadPage[],
+  pageLinks: PreloadPageLink[],
+  elements: PreloadElement[],
+  options?: AssetDiscoveryOptions,
+): AssetToCache[]
+
+// Get prioritized assets for current page + neighbors (online preload)
+getPrioritizedAssets(
+  currentPageId: string,
+  pages: PreloadPage[],
+  pageLinks: PreloadPageLink[],
+  elements: PreloadElement[],
+  neighborPageIds: Array<{ pageId: string; distance: number }>,
+  options?: AssetDiscoveryOptions,
+): AssetToCache[]
+```
+
+### AssetToCache Interface
+
+```typescript
+interface AssetToCache {
+  storageKey: string;      // Canonical storage key for caching
+  originalUrl: string;     // Original URL from page/element data
+  assetType: AssetType;    // 'image' | 'video' | 'audio' | 'transition' | 'other'
+  pageId: string;          // Page this asset belongs to
+  priority: number;        // Download priority (higher = first)
+  sizeBytes?: number;      // Estimated size in bytes
+  isTransition?: boolean;  // True for transition videos
+}
+```
+
+### Asset Sources
+
+The discovery system extracts assets from:
+
+1. **Page backgrounds** - `background_image_url`, `background_video_url`, `background_audio_url`
+2. **Element content_json** - All URL fields defined in `PRELOAD_CONFIG.assetFields.all`
+3. **Transition videos** - `transition.video_url` from page links
+4. **Nested assets** - `galleryCards[].imageUrl`, `carouselSlides[].videoUrl`, etc.
+
+### URL Fields Scanned
+
+```typescript
+// From PRELOAD_CONFIG.assetFields.all
+[
+  'iconUrl', 'imageUrl', 'mediaUrl', 'videoUrl', 'audioUrl',
+  'transitionVideoUrl', 'backgroundImageUrl', 'reverseVideoUrl',
+  'carouselPrevIconUrl', 'carouselNextIconUrl', 'src', 'url',
+  'poster', 'thumbnail'
+]
+```
+
+### AssetCacheService
+
+Unified service for both online preload and offline download:
+
+```typescript
+class AssetCacheService {
+  // Discover assets (single source of truth)
+  static discoverProjectAssets(pages, pageLinks, elements, options?): AssetToCache[]
+  static getPrioritizedAssets(currentPageId, pages, pageLinks, elements, neighbors, options?): AssetToCache[]
+
+  // Check cache status
+  static async getAssetInfo(storageKey): Promise<CachedAssetInfo | null>
+  static async checkCacheStatus(storageKeys): Promise<Map<string, CachedAssetInfo>>
+  static async filterAssetsNeedingDownload(assets, mode): Promise<AssetToCache[]>
+
+  // Queue downloads
+  static async queueDownloads(assets, options: QueueDownloadOptions): Promise<void>
+
+  // Resolve download URL (presigned or proxy)
+  static resolveDownloadUrl(storageKey, presignedUrls?): string
+
+  // Cache utilities
+  static async clearProjectCache(projectId): Promise<void>
+  static getReadyBlobUrl(url): string | null
+  static hasReadyBlobUrl(url): boolean
+}
+```
+
+### CachedAssetInfo Interface
+
+```typescript
+interface CachedAssetInfo {
+  storageKey: string;
+  exists: boolean;
+  isPartial: boolean;    // True for partial downloads (need full for offline)
+  sizeBytes: number;
+  downloadedAt?: number;
+}
+```
+
+### Usage in useOfflineMode
+
+```typescript
+// frontend/src/hooks/useOfflineMode.ts
+
+const discoverAssets = useCallback((): AssetToCache[] => {
+  if (!pages || pages.length === 0) return [];
+
+  // Extract pageLinks and elements from all pages
+  const { pageLinks, preloadElements } = extractPageLinksAndElements(pages);
+
+  // Use shared asset discovery (same as online preload)
+  return discoverProjectAssets(pages, pageLinks, preloadElements);
+}, [pages]);
+
+const startDownload = useCallback(async () => {
+  const assets = discoverAssets();
+  // ... queue downloads using discovered assets
+}, [discoverAssets]);
+```
+
+---
+
+## Offline Types
+
+Location: `frontend/src/types/offline.ts`
+
+```typescript
+// Project status
+type ProjectOfflineStatus =
+  | 'not_downloaded'
+  | 'downloading'
+  | 'downloaded'
+  | 'outdated'
+  | 'error';
+
+// Asset variant types
+type AssetVariantType =
+  | 'thumbnail'
+  | 'preview'
+  | 'webp'
+  | 'mp4_low'
+  | 'mp4_high'
+  | 'original';
+
+// Asset types
+type AssetType =
+  | 'image'
+  | 'video'
+  | 'audio'
+  | 'transition'
+  | 'other';
+
+// Preload job status
+type PreloadJobStatus =
+  | 'queued'
+  | 'downloading'
+  | 'completed'
+  | 'error'
+  | 'paused';
+
+// Storage quota info
+interface StorageQuotaInfo {
+  usage: number;
+  quota: number;
+  percentUsed: number;
+  available: number;
+  canStore: (bytes: number) => boolean;
+}
+
+// Network information
+interface NetworkInfo {
+  isOnline: boolean;
+  effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
+  downlink?: number;
+  rtt?: number;
+  saveData?: boolean;
+}
+
+// Cache status for an asset (from StorageManager.getAssetInfo)
+interface CachedAssetInfo {
+  storageKey: string;
+  exists: boolean;
+  isPartial: boolean;    // True for partial downloads
+  sizeBytes: number;
+  downloadedAt?: number;
+}
+
+// Asset to cache (from assetDiscovery)
+interface AssetToCache {
+  storageKey: string;
+  originalUrl: string;
+  assetType: AssetType;
+  pageId: string;
+  priority: number;
+  sizeBytes?: number;
+  isTransition?: boolean;
+}
+
+// Preload state
+interface PreloadState {
+  isActive: boolean;
+  currentPageId: string | null;
+  queuedAssets: string[];
+  loadingAssets: string[];
+  completedAssets: string[];
+  failedAssets: string[];
+  totalProgress: number;
+}
+
+// Neighbor graph
+interface NeighborGraph {
+  connections: Map<string, Array<{ pageId: string; distance: number }>>;
+  getNeighbors: (pageId: string, maxDepth: number) => string[];
+  getAssetsForPages: (pageIds: string[]) => string[];
+}
+```
+
+---
+
+## Key Workflows
+
+### A. Project Download for Offline Use
+
+```
+1. User clicks OfflineToggle button
+   └── useOfflineMode.startDownload()
+
+2. Discover assets from pages (frontend-only, no backend call)
+   └── discoverProjectAssets(pages, pageLinks, preloadElements)
+   └── Same asset discovery as online preload
+
+3. Check which assets need downloading
+   └── StorageManager.getAssetInfo(storageKey) for each
+   └── Skip fully cached, re-download partial for offline
+
+4. Check storage quota
+   └── StorageManager.getStorageQuota()
+   └── Ensure sufficient space available
+
+5. Create project record in IndexedDB
+   └── OfflineDbManager.upsertProject()
+
+6. Fetch presigned URLs for S3 assets
+   └── queuePresignedUrls(storagePaths)
+   └── Falls back to proxy if presigning fails
+
+7. Initialize download queue
+   └── downloadManager.addJob() for each asset
+   └── Full downloads (no maxBytes) for offline
+
+8. Process downloads
+   └── Priority-based concurrent downloads (max 3)
+   └── Stream with progress tracking
+   └── Auto-fallback: presigned URL → proxy on CORS error
+
+9. Store assets
+   └── < 5MB → Cache API
+   └── ≥ 5MB → IndexedDB
+   └── With isPartial: false for offline completeness
+
+10. Track progress via events
+    └── Update project status in IndexedDB
+    └── Emit events via DownloadEventBus (includes storageKey)
+
+11. Complete
+    └── Mark project as 'downloaded'
+    └── Emit projectDownloadComplete event
+```
+
+### B. Offline Asset Retrieval
+
+```
+1. App requests asset (by storage path)
+   └── e.g., storagePath = 'assets/project-123/video.mp4'
+
+2. Try in-memory lookup first (O(1) instant)
+   └── getReadyBlobUrl(storagePath)
+   └── Returns pre-decoded blob URL if available
+
+3. Try Cache API by storage key
+   └── getCachedBlobUrl(storagePath)
+   └── Works after page refresh (in-memory cleared)
+
+4. Try resolved URL lookups (fallback)
+   └── getReadyBlobUrl(resolvedUrl)
+   └── getCachedBlobUrl(resolvedUrl)
+
+5. If found
+   └── Create blob URL: URL.createObjectURL(blob)
+   └── Return for playback
+
+6. If not found
+   └── Try network fetch (if online)
+   └── Or show offline error
+```
+
+**Lookup Priority:**
+```
+1. getReadyBlobUrl(storageKey)   → O(1) instant (same session)
+2. getCachedBlobUrl(storageKey)  → Cache API (~5ms, post-refresh)
+3. getReadyBlobUrl(resolvedUrl)  → fallback
+4. getCachedBlobUrl(resolvedUrl) → fallback
+5. Network fetch                 → last resort
+```
+
+### C. Resume Interrupted Downloads
+
+```
+1. Page loads
+   └── downloadManager.restoreQueue()
+
+2. Query IndexedDB
+   └── OfflineDbManager.getPendingQueue()
+   └── Get pending/paused queue items
+
+3. Resume downloads
+   └── Re-add to in-memory queue
+   └── Sort by priority
+   └── Continue processing
+
+4. Update progress
+   └── Emit events for UI
+```
+
+### D. Check for Updates
+
+```
+1. App calls useOfflineMode.checkForUpdates()
+
+2. Discover current assets from pages
+   └── discoverProjectAssets(pages, pageLinks, preloadElements)
+
+3. Compare with stored project info
+   └── If asset count changed, set status to 'outdated'
+
+4. User can re-download
+   └── deleteOfflineData() then startDownload()
+```
+
+---
+
+## Configuration Reference
+
+### Preload Configuration
+
+Location: `frontend/src/config/preload.config.ts`
+
+```typescript
+export const PRELOAD_CONFIG = {
+  // Queue settings
+  maxConcurrentDownloads: 3,
+  maxRetries: 3,
+  retryDelayMs: 1000,
+
+  // Size thresholds
+  largeFileThreshold: 5 * 1024 * 1024,  // 5MB -> use IndexedDB
+  videoChunkSize: 5 * 1024 * 1024,       // 5MB chunks
+  initialVideoBufferSeconds: 5,
+
+  // Priority weights (higher = load first)
+  priority: {
+    currentPage: 1000,
+    neighborBase: 500,
+    assetType: {
+      transition: 150,  // Highest - needed immediately on navigation click
+      image: 100,
+      audio: 50,
+      video: 30,
+    },
+    variant: {
+      thumbnail: 50,
+      preview: 40,
+      webp: 35,
+      mp4_low: 20,
+      mp4_high: 10,
+      original: 5,
+    },
+    linkCountMultiplier: 10,
+    maxLinkBonus: 50,
+  },
+
+  // Storage warnings
+  storage: {
+    warningPercent: 80,
+    criticalPercent: 95,
+    minFreeBuffer: 50 * 1024 * 1024,  // 50MB
+  },
+
+  // Auto-cleanup timeouts
+  autoRemove: {
+    completedMs: 3000,
+    errorMs: 10000,
+  },
+
+  // Neighbor graph traversal
+  neighborGraph: {
+    maxDepth: 1,              // Only preload immediate neighbors (reduced from 2)
+    constructorMaxDepth: 1,   // Same as maxDepth for constructor
+  },
+
+  // Asset URL field names in element content_json
+  assetFields: {
+    all: [
+      'iconUrl', 'imageUrl', 'mediaUrl', 'videoUrl', 'audioUrl',
+      'transitionVideoUrl', 'backgroundImageUrl', 'reverseVideoUrl',
+      'carouselPrevIconUrl', 'carouselNextIconUrl',
+      'src', 'url', 'poster', 'thumbnail',
+    ],
+    images: [
+      'iconUrl', 'imageUrl', 'backgroundImageUrl',
+      'carouselPrevIconUrl', 'carouselNextIconUrl', 'src',
+    ],
+    nested: ['galleryCards', 'carouselSlides'],
+    nestedUrlFields: ['imageUrl', 'videoUrl'],
+  },
+};
+```
+
+### Offline Configuration
+
+Location: `frontend/src/config/offline.config.ts`
+
+```typescript
+export const OFFLINE_CONFIG = {
+  // IndexedDB
+  dbName: 'TourBuilderOffline',
+  dbVersion: 1,
+
+  // Cache names (for Cache API)
+  cacheNames: {
+    static: 'tour-builder-static-v1',
+    dynamic: 'tour-builder-dynamic-v1',
+    assets: 'tour-builder-assets-v1',
+  },
+
+  // Events (EventEmitter event names)
+  events: {
+    preloadStart: 'asset-preload-start',
+    preloadProgress: 'asset-preload-progress',
+    preloadComplete: 'asset-preload-complete',
+    preloadError: 'asset-preload-error',
+    projectDownloadProgress: 'project-download-progress',
+    projectDownloadComplete: 'project-download-complete',
+    queueUpdate: 'queue-update',
+  },
+
+  // Service worker settings
+  serviceWorker: {
+    scope: '/',
+    updateInterval: 60 * 60 * 1000,  // 1 hour
+  },
+
+  // Storage settings
+  storage: {
+    cacheApiMaxSize: 5 * 1024 * 1024,   // 5MB
+    indexedDbMinSize: 5 * 1024 * 1024,  // 5MB
+  },
+
+  // Retry settings
+  retry: {
+    maxRetries: 3,
+    backoffMs: 1000,
+    maxBackoffMs: 30000,
+  },
+};
+```
+
+---
+
+## Key Files Reference
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `sw.ts` | `frontend/src/` | Service worker implementation |
+| `offline.config.ts` | `frontend/src/config/` | Offline settings |
+| `preload.config.ts` | `frontend/src/config/` | Preload settings |
+| `StorageManager.ts` | `frontend/src/lib/offline/` | Dual-storage abstraction |
+| `DownloadManager.ts` | `frontend/src/lib/offline/` | Download queue with auto proxy fallback |
+| `DownloadEventBus.ts` | `frontend/src/lib/offline/` | Event emitter |
+| `OfflineDbManager.ts` | `frontend/src/lib/offlineDb/` | IndexedDB operations |
+| `schema.ts` | `frontend/src/lib/offlineDb/` | Dexie schema |
+| `AssetCacheService.ts` | `frontend/src/lib/assetCache/` | Unified asset caching service |
+| `assetDiscovery.ts` | `frontend/src/lib/assetCache/` | Shared asset extraction logic |
+| `assetUrl.ts` | `frontend/src/lib/` | Presigned URL cache and resolution |
+| `extractPageLinks.ts` | `frontend/src/lib/` | Extract navigation targets from pages |
+| `usePreloadOrchestrator.ts` | `frontend/src/hooks/` | Asset preloading with ready blob URLs |
+| `usePageSwitch.ts` | `frontend/src/hooks/` | Page navigation using preloaded assets |
+| `useOfflineMode.ts` | `frontend/src/hooks/` | Project offline orchestration (frontend discovery) |
+| `useStorageQuota.ts` | `frontend/src/hooks/` | Storage quota monitoring |
+| `useNetworkAware.ts` | `frontend/src/hooks/` | Network detection |
+| `OfflineToggle.tsx` | `frontend/src/components/Offline/` | Offline toggle button |
+| `OfflineStatusIndicator.tsx` | `frontend/src/components/Offline/` | Offline status display |
+| `StorageUsageDisplay.tsx` | `frontend/src/components/Offline/` | Storage quota visualization |
+| `DownloadProgressPanel.tsx` | `frontend/src/components/Offline/` | Download progress panel |
+| `usePWAPreload.ts` | `frontend/src/hooks/` | PWA preload orchestration |
+| `offline.ts` | `frontend/src/types/` | Type definitions |
+
+---
+
+## Browser Requirements
+
+| Feature | Support |
+|---------|---------|
+| Service Workers | All modern browsers |
+| IndexedDB | All modern browsers (Dexie handles differences) |
+| Cache API | All modern browsers |
+| Network Information API | Chrome, Edge, Firefox (graceful degradation) |
+| Blob URLs | All modern browsers |
+| navigator.storage.persist() | Most modern browsers |
+| Response streaming | All modern browsers |
+
+---
+
+## Troubleshooting
+
+### Downloads Not Starting
+1. Check network connectivity
+2. Verify storage quota available (`useStorageQuota`)
+3. Check browser console for errors
+4. Ensure Service Worker registered
+5. Verify project ID is valid
+
+### Assets Not Loading Offline
+1. Verify assets in IndexedDB/Cache API (DevTools → Application tab)
+2. Check Service Worker fetch handler
+3. Look for CORS issues
+4. Verify blob URL creation
+5. Check `StorageManager.hasAsset(url)` returns true
+
+### Storage Quota Exceeded
+1. Clear old project downloads (`deleteOfflineData`)
+2. Delete unused cached assets
+3. Request persistent storage (`requestPersistence`)
+4. Reduce asset quality (use mobile variant)
+5. Check `isCritical` flag from `useStorageQuota`
+
+### Download Resume Not Working
+1. Check IndexedDB downloadQueue table (DevTools → Application → IndexedDB)
+2. Verify `restoreQueue()` called on load
+3. Check for corrupted queue items
+4. Clear queue and re-download
+
+### Video Seeking Issues Offline
+1. Verify video is in cache (check DevTools → Application → Cache Storage)
+2. Check video cached with proper Content-Type header
+3. Ensure Range request handler working (check Network tab for 206 responses)
+4. Test with smaller video file
+5. Check if video is in IndexedDB (for large files > 5MB)
+
+### Progress Not Updating
+1. Verify DownloadEventBus subscriptions
+2. Check for event name mismatches (use `OFFLINE_CONFIG.events.*`)
+3. Ensure handler is not unsubscribed prematurely
+4. Check for errors in event handler (caught silently by bus)
+
+### useOfflineMode Not Working
+1. Verify `projectId` is not null
+2. Check `enabled` option (default: true)
+3. Verify `pages` prop is provided (required for asset discovery)
+4. Verify `isOfflineCapable` is true (SW + caches supported)
+5. Check browser console for `[useOfflineMode]` logs
diff --git a/documentation/page-links-navigation.md b/documentation/page-links-navigation.md
new file mode 100644
index 0000000..c30a03f
--- /dev/null
+++ b/documentation/page-links-navigation.md
@@ -0,0 +1,572 @@
+# Page Navigation
+
+Documentation for the Tour Builder Platform's page navigation system using element-based navigation stored in `ui_schema_json`.
+
+## Overview
+
+The platform uses a simplified navigation system where navigation configuration is stored directly in `tour_pages.ui_schema_json` as part of element definitions. This approach:
+- Eliminates ID remapping issues when publishing between environments
+- Uses page slugs instead of UUIDs for cross-environment consistency
+- Stores transition video URLs directly on navigation elements
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      Page Navigation Architecture                            │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                       Navigation Source                                 │ │
+│  │                                                                         │ │
+│  │   ┌─────────────────────────────────────────────────────────┐          │ │
+│  │   │            tour_pages.ui_schema_json                    │          │ │
+│  │   │                                                          │          │ │
+│  │   │  elements: [{                                            │          │ │
+│  │   │    type: "navigation_next",                              │          │ │
+│  │   │    targetPageSlug: "page-2",                             │          │ │
+│  │   │    transitionVideoUrl: "assets/.../video.mp4",           │          │ │
+│  │   │    ...                                                   │          │ │
+│  │   │  }]                                                      │          │ │
+│  │   └─────────────────────────────────────────────────────────┘          │ │
+│  │                              │                                          │ │
+│  │                              ▼                                          │ │
+│  │              ┌───────────────────────────────┐                          │ │
+│  │              │     Navigation Resolution     │                          │ │
+│  │              │                               │                          │ │
+│  │              │  • Resolve slug to page       │                          │ │
+│  │              │  • Determine direction        │                          │ │
+│  │              │  • Get preloaded blob URL     │                          │ │
+│  │              └───────────────┬───────────────┘                          │ │
+│  │                              │                                          │ │
+│  │              ┌───────────────┴───────────────┐                          │ │
+│  │              ▼                               ▼                          │ │
+│  │   ┌──────────────────┐            ┌──────────────────┐                 │ │
+│  │   │ With Transition  │            │ Direct Navigate  │                 │ │
+│  │   │                  │            │                  │                 │ │
+│  │   │ Play video →     │            │ Switch page →    │                 │ │
+│  │   │ Switch page      │            │ Update history   │                 │ │
+│  │   └──────────────────┘            └──────────────────┘                 │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Data Model
+
+### Navigation in ui_schema_json
+
+Navigation is configured directly within element objects in the `tour_pages.ui_schema_json` field:
+
+```typescript
+// Element with navigation configuration
+{
+  id: "element-uuid",
+  type: "navigation_next",  // or "navigation_prev"
+  label: "Next Page Button",
+
+  // Position
+  xPercent: 90,
+  yPercent: 85,
+
+  // Navigation Configuration
+  navigationTargetMode: "target_page",     // "target_page" or "external_url"
+  targetPageSlug: "page-2",              // Slug-based navigation (consistent across environments)
+  externalUrl: undefined,                 // Used when navigationTargetMode is "external_url"
+  transitionVideoUrl: "assets/transitions/fade.mp4",
+  transitionDurationSec: 0.7,
+  transitionReverseMode: "auto_reverse", // or "separate_video"
+  reverseVideoUrl: undefined,            // Only used with "separate_video" mode
+
+  // Element Styling
+  iconUrl: "assets/icons/arrow-right.png",
+  // ... extends ElementStyleProperties
+}
+```
+
+### Key Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | string | `navigation_next` or `navigation_prev` determines direction |
+| `navigationTargetMode` | `'target_page'` \| `'external_url'` | Destination mode for forward navigation buttons. Defaults to `target_page` |
+| `targetPageSlug` | string | Target page slug (NOT UUID) for cross-environment consistency |
+| `externalUrl` | string | External URL opened in a new tab when `navigationTargetMode` is `external_url` |
+| `transitionVideoUrl` | string | URL to transition video (optional) |
+| `transitionDurationSec` | number | Duration in seconds (optional) |
+| `transitionReverseMode` | `'auto_reverse'` \| `'separate_video'` | Reverse playback mode (replaces deprecated `supportsReverse`) |
+| `reverseVideoUrl` | string | Separate video URL for reverse playback (when mode is `separate_video`) |
+
+### Why Slugs Instead of UUIDs
+
+Previous versions used `targetPageId` (UUID) which caused issues:
+- When pages are copied between environments (dev → stage → production), UUIDs change
+- References to old UUIDs became invalid after publishing
+
+The slug-based approach solves this:
+- Slugs are unique within project+environment
+- Slugs remain identical across environments (same page has same slug in dev/stage/prod)
+- No ID remapping needed during publish
+
+## Navigation Types
+
+### Forward Navigation (`navigation_next`)
+
+Navigates to a specified target page with optional transition.
+
+```typescript
+{
+  type: "navigation_next",
+  navigationTargetMode: "target_page",
+  targetPageSlug: "gallery",
+  transitionVideoUrl: "assets/transitions/zoom-in.mp4",
+  transitionReverseMode: "auto_reverse"
+}
+```
+
+**Behavior:**
+- Target page resolved by slug
+- Transition video plays forward if specified
+- Page added to navigation history
+
+### External URL Navigation (`navigation_next`)
+
+Forward navigation buttons can open an external URL instead of targeting a tour page:
+
+```typescript
+{
+  type: "navigation_next",
+  navType: "forward",
+  navigationTargetMode: "external_url",
+  externalUrl: "https://example.com"
+}
+```
+
+**Behavior:**
+- The button is treated as forward navigation
+- Target page selection is disabled and `targetPageSlug` / `targetPageId` are cleared
+- The URL opens in a new tab with `noopener,noreferrer`
+- If the URL omits `http://` or `https://`, the runtime opens it with an `https://` prefix
+- External URL buttons are not included in internal page-link extraction, neighbor preloading, or reversed transition video generation
+
+### Back Navigation (`navigation_prev`)
+
+Returns to previous page with optional reverse transition.
+
+```typescript
+{
+  type: "navigation_prev",
+  targetPageSlug: "home",  // Optional - can use history
+  transitionVideoUrl: "assets/transitions/zoom-in.mp4",
+  transitionReverseMode: "auto_reverse"  // Plays in reverse for back nav
+}
+```
+
+**Alternative with separate reverse video:**
+
+```typescript
+{
+  type: "navigation_prev",
+  targetPageSlug: "home",
+  transitionVideoUrl: "assets/transitions/zoom-in.mp4",
+  transitionReverseMode: "separate_video",
+  reverseVideoUrl: "assets/transitions/zoom-out.mp4"
+}
+```
+
+**Behavior:**
+- Target page optional (uses page history)
+- If `transitionReverseMode = 'auto_reverse'`, video plays in reverse
+- If `transitionReverseMode = 'separate_video'`, uses `reverseVideoUrl` instead
+- Page popped from navigation history
+
+## Navigation Flow
+
+### Runtime Resolution
+
+**Files:**
+- `frontend/src/components/RuntimePresentation.tsx`
+- `frontend/src/lib/navigationHelpers.ts`
+
+Navigation uses `resolveNavigationTarget` helper and `usePageSwitch` hook:
+
+```typescript
+import { resolveNavigationTarget, isTransitionBlocking } from '../lib/navigationHelpers';
+
+// Extract navigation links from pages
+const { pageLinks, preloadElements } = extractPageLinksAndElements(pages);
+
+// Initialize preload orchestrator
+const preloadOrchestrator = usePreloadOrchestrator({
+  pages,
+  pageLinks,
+  elements: preloadElements,
+  currentPageId: selectedPageId,
+  enabled: !isLoading,
+});
+
+// Initialize page switch with preload cache
+const pageSwitch = usePageSwitch({
+  preloadCache: {
+    getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,  // O(1) instant lookup
+    getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+    preloadedUrls: preloadOrchestrator.preloadedUrls,
+  },
+});
+
+// Handle navigation element click
+const handleElementClick = useCallback((element) => {
+  // Block navigation during active transitions
+  if (isTransitionBlocking(transitionPhase, isBuffering)) {
+    return;
+  }
+
+  // Resolve target page (supports both slug and legacy ID)
+  const navTarget = resolveNavigationTarget(element, pages);
+  if (!navTarget) return;
+
+  // Navigate with transition if configured
+  if (element.transitionVideoUrl) {
+    // Start transition playback, then switch page on completion
+    startTransition({
+      videoUrl: element.transitionVideoUrl,
+      storageKey: element.transitionVideoUrl,  // Raw path for cache lookup
+      reverseMode: navTarget.isBack ? getReverseMode(element) : 'none',
+      reverseVideoUrl: element.reverseVideoUrl,
+      targetPageId: navTarget.pageId,
+    });
+  } else {
+    // Direct navigation (no transition)
+    pageSwitch.switchToPage(navTarget.page, () => {
+      setSelectedPageId(navTarget.pageId);
+    });
+  }
+}, [pages, pageSwitch, transitionPhase, isBuffering]);
+```
+
+**Navigation Target Resolution (`navigationHelpers.ts`):**
+
+```typescript
+// Supports both targetPageSlug (preferred) and targetPageId (legacy)
+export const resolveNavigationTarget = (element, pages) => {
+  let targetPage;
+  if (element.targetPageSlug) {
+    targetPage = pages.find(p => p.slug === element.targetPageSlug);
+  } else if (element.targetPageId) {
+    targetPage = pages.find(p => p.id === element.targetPageId);
+  }
+  if (!targetPage) return null;
+
+  const isBack = element.navType === 'back' || element.type === 'navigation_prev';
+  return {
+    page: targetPage,
+    pageId: targetPage.id,
+    transitionVideoUrl: element.transitionVideoUrl,
+    isBack,
+  };
+};
+```
+
+### Page History Management
+
+Page history is managed by the shared `usePageNavigation` hook (used by both RuntimePresentation and constructor):
+
+```typescript
+import { usePageNavigation } from '../hooks/usePageNavigation';
+
+// Hook provides unified history management with browser-like behavior
+const {
+  currentPageId: selectedPageId,
+  pageHistory,
+  previousPageId,
+  applyPageSelection,
+  getNavigationContext,
+} = usePageNavigation({
+  pages,
+  defaultPageId: initialPageId,
+  trackHistory: true,
+});
+
+// applyPageSelection handles history automatically:
+// - Forward (isBack=false): appends to history, trimmed to MAX_HISTORY_LENGTH=50
+// - Back (isBack=true): pops from history if target matches previousPageId
+applyPageSelection(targetPageId, isBack);
+
+// getNavigationContext provides context for history-based back navigation
+const navContext = getNavigationContext();
+// Returns: { currentPageSlug, previousPageId }
+const navTarget = resolveNavigationTarget(element, pages, navContext);
+```
+
+**History Behavior:**
+```
+Forward: A → B → C → history: [A, B, C]
+Back to B (isBack=true): → history: [A, B]  ✓ Pops C
+Back to A (isBack=true): → history: [A]     ✓ Pops B
+Forward to D: → history: [A, D]             ✓ Adds D
+```
+
+## Transition Playback
+
+### With Video Transition
+
+```typescript
+// useTransitionPlayback handles video playback with preload cache integration
+const { phase, isBuffering, isReversing, cancel, forceComplete } = useTransitionPlayback({
+  videoRef,
+  transition: transitionConfig,  // { videoUrl, storageKey, reverseMode, reverseVideoUrl, targetPageId, isBack }
+  // onComplete receives isBack flag for proper history management
+  onComplete: (targetPageId, isBack) => {
+    // Transition finished, switch to target page
+    pageSwitch.switchToPage(targetPage, () => {
+      // usePageNavigation hook: pops history on back, appends on forward
+      applyPageSelection(targetPageId, isBack ?? false);
+    });
+  },
+  preload: {
+    preloadedUrls: preloadOrchestrator.preloadedUrls,
+    getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+    getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,
+  },
+});
+```
+
+**Storage Key Mapping:**
+The `storageKey` (raw storage path like `assets/project/transition.mp4`) is preserved for cache lookup because presigned URL signatures change on each resolution. The lookup priority is:
+1. `getReadyBlobUrl(storageKey)` → O(1) instant (same session)
+2. `getCachedBlobUrl(storageKey)` → Cache API (~5ms, post-refresh)
+3. Fallback to resolved URL lookup
+
+### Reverse Playback
+
+When navigating back with `transitionReverseMode = 'auto_reverse'`:
+- Video plays from end to beginning using `useReversePlayback` hook
+- Supports native `playbackRate = -1` or frame-stepping fallback
+
+```typescript
+const {
+  startReverse,
+  stopReverse,
+  isReversing,
+  isBuffering,
+  canUseNativeReverse,
+} = useReversePlayback({
+  videoRef,
+  onComplete: finishOverlayTransition,
+  preloadedUrls,
+  videoUrl,
+  getCachedBlobUrl,
+});
+
+// For back navigation with auto_reverse mode
+if (isBack && transitionReverseMode === 'auto_reverse') {
+  startReverse();
+}
+```
+
+**Reverse Mode Options:**
+
+| Mode | Behavior |
+|------|----------|
+| `none` | No transition on back navigation |
+| `auto_reverse` | Same video plays in reverse |
+| `separate_video` | Uses `reverseVideoUrl` for back navigation |
+
+## Constructor Configuration
+
+### Setting Up Navigation
+
+**File:** `frontend/src/pages/constructor.tsx`
+
+When creating/editing navigation elements:
+
+1. Select element type (`navigation_next` or `navigation_prev`)
+2. Choose target page from dropdown (shows page names/slugs)
+3. Optionally select transition video from assets
+4. Configure transition settings (duration, reverse support)
+
+```typescript
+// Saving navigation element
+const elementData = {
+  type: selectedElementType,
+  targetPageSlug: targetPage?.slug,  // Save slug, not ID
+  transitionVideoUrl: selectedTransitionVideo?.cdn_url,
+  transitionDurationSec: transitionDuration,
+  transitionReverseMode: supportsReverse ? 'auto_reverse' : undefined,
+  reverseVideoUrl: reverseMode === 'separate_video' ? reverseVideo?.cdn_url : undefined,
+};
+```
+
+### Extracting Navigation Links for Preloading
+
+**File:** `frontend/src/lib/extractPageLinks.ts`
+
+The `extractPageLinksAndElements` utility extracts navigation targets and preloadable elements from pages:
+
+```typescript
+import { extractPageLinksAndElements } from '../lib/extractPageLinks';
+
+// Extract from all pages (filtered by environment)
+const filteredPages = pages.filter(p => p.environment === environment);
+const { pageLinks, preloadElements } = extractPageLinksAndElements(filteredPages);
+
+// pageLinks: Array of navigation connections
+// [{ sourcePageId, targetPageSlug, transitionVideoUrl, supportsReverse }]
+
+// preloadElements: Array of elements with preloadable assets
+// [{ pageId, type, imageUrl, videoUrl, transitionVideoUrl, ... }]
+```
+
+### Building Neighbor Graph
+
+**File:** `frontend/src/hooks/useNeighborGraph.ts`
+
+The neighbor graph is built from pageLinks for preload prioritization:
+
+```typescript
+const neighborGraph = useNeighborGraph({
+  pages: filteredPages,
+  pageLinks,          // From extractPageLinksAndElements
+  currentPageId,
+  maxDepth: 1,        // Only immediate neighbors (reduced from 2)
+});
+
+// Returns pages reachable within maxDepth hops
+const neighborsToPreload = neighborGraph.getNeighbors(currentPageId);
+```
+
+**Preload Priority for Navigation Assets:**
+| Asset Type | Priority | Notes |
+|------------|----------|-------|
+| Transition video | +150 | Highest - needed immediately on click |
+| Background image | +100 | Required for page display |
+| Audio | +50 | Background audio tracks |
+| Video | +30 | Can stream, lower priority |
+
+## TypeScript Types
+
+**File:** `frontend/src/types/constructor.ts`
+
+```typescript
+// Navigation-related fields in CanvasElement
+interface CanvasElement extends BaseCanvasElement {
+  id: string;
+  type: CanvasElementType;  // 'navigation_next' | 'navigation_prev' | ...
+  label: string;
+
+  // Position
+  xPercent: number;
+  yPercent: number;
+
+  // Navigation (for navigation_next, navigation_prev types)
+  navType?: NavigationButtonKind;  // 'forward' | 'back'
+  navDisabled?: boolean;
+  /** @deprecated Use targetPageSlug instead */
+  targetPageId?: string;
+  targetPageSlug?: string;
+  transitionVideoUrl?: string;
+  transitionReverseMode?: 'auto_reverse' | 'separate_video';
+  reverseVideoUrl?: string;
+  transitionDurationSec?: number;
+
+  // Styling
+  iconUrl?: string;
+  // ... extends ElementStyleProperties for CSS styling
+}
+
+// Navigation button direction type
+type NavigationButtonKind = 'forward' | 'back';
+```
+
+**File:** `frontend/src/types/presentation.ts`
+
+```typescript
+// Navigation target resolved from element
+interface NavigationTarget {
+  page: RuntimePage;
+  pageId: string;
+  transitionVideoUrl?: string;
+  isBack: boolean;
+}
+
+// Element with navigation properties (for click handling)
+interface NavigableElement {
+  id: string;
+  type: string;
+  targetPageSlug?: string;
+  targetPageId?: string;      // Legacy
+  transitionVideoUrl?: string;
+  navType?: 'forward' | 'back';
+  navDisabled?: boolean;
+}
+
+// Transition phase states
+type TransitionPhase = 'idle' | 'preparing' | 'playing' | 'reversing' | 'completed';
+```
+
+## File References
+
+| File | Purpose |
+|------|---------|
+| `frontend/src/pages/constructor.tsx` | Navigation element configuration |
+| `frontend/src/components/RuntimePresentation.tsx` | Runtime navigation execution |
+| `frontend/src/lib/extractPageLinks.ts` | Extract navigation links and preload elements from pages |
+| `frontend/src/lib/navigationHelpers.ts` | Navigation target resolution and direction detection |
+| `frontend/src/hooks/usePageSwitch.ts` | Page navigation with preloaded blob URLs |
+| `frontend/src/hooks/usePreloadOrchestrator.ts` | Asset preloading with ready blob URL management |
+| `frontend/src/hooks/usePageNavigation.ts` | History and page state management |
+| `frontend/src/hooks/useNeighborGraph.ts` | Preload graph from navigation |
+| `frontend/src/hooks/useReversePlayback.ts` | Reverse video playback (native or frame-stepping) |
+| `frontend/src/hooks/useTransitionPlayback.ts` | Transition video playback with preloaded URLs |
+| `frontend/src/types/constructor.ts` | Element type definitions |
+| `frontend/src/types/presentation.ts` | Navigation target and element interfaces |
+| `frontend/src/config/preload.config.ts` | Preload priority weights and settings |
+
+`extractPageLinks.ts` also extracts nested Info Panel `target_page` destinations from `infoPanelSections`:
+- section-level header/title/text click destinations
+- span item click destinations
+- image/card/video/360 item click destinations
+
+External URL destinations are not added to the neighbor graph. Info Panel nested media URLs (`imageUrl`, `videoUrl`, `iconUrl`, and header images) are recursively extracted into preload elements.
+
+## Environment Filtering
+
+Pages are filtered by environment before navigation resolution:
+
+```typescript
+// Filter pages by current environment (dev, stage, production)
+const filteredPages = pages.filter(p => p.environment === environment);
+
+// Extract navigation links only from same-environment pages
+const { pageLinks, preloadElements } = extractPageLinksAndElements(filteredPages);
+
+// Navigation only resolves within the same environment
+const targetPage = filteredPages.find(p => p.slug === element.targetPageSlug);
+```
+
+**Environment Contexts:**
+| Context | Environment | Notes |
+|---------|-------------|-------|
+| Constructor | `dev` | Editing/preview mode |
+| Stage preview | `stage` | Pre-production review |
+| Public runtime | `production` | Published tour playback |
+
+Navigation links pointing to slugs that don't exist in the current environment will fail silently.
+
+## Known Considerations
+
+### 1. Slug Uniqueness
+
+Slugs must be unique within project+environment. The system validates this on page creation/update.
+
+### 2. Missing Target Pages
+
+If `targetPageSlug` references a non-existent page in the current environment, navigation silently fails. UI should handle gracefully.
+
+### 3. Transition Reverse Support
+
+Not all transitions look good in reverse. Use `transitionReverseMode: 'separate_video'` with a dedicated `reverseVideoUrl` for directional animations, or omit reverse mode entirely.
+
+### 4. Preloading
+
+Navigation elements drive preloading. Transition videos have highest priority (+150) and are preloaded first. The neighbor graph uses `maxDepth: 1` (immediate neighbors only).
+
+### 5. Instant Navigation with Preloaded Assets
+
+When assets are preloaded, `usePageSwitch` uses `getReadyBlobUrl(storageKey)` for O(1) instant lookup of pre-decoded blob URLs, eliminating any delay or flash during navigation. Lookups prioritize storage keys (e.g., `assets/project/bg.jpg`) over resolved URLs because storage keys are canonical and don't change when presigned URLs are regenerated.
diff --git a/documentation/page-transitions.md b/documentation/page-transitions.md
new file mode 100644
index 0000000..1559f75
--- /dev/null
+++ b/documentation/page-transitions.md
@@ -0,0 +1,941 @@
+# Page Transitions Feature
+
+Documentation for the Tour Builder Platform's page transition system using video-based animations stored directly on navigation elements.
+
+## Overview
+
+The platform implements video-based page transitions that are configured directly on navigation elements in `tour_pages.ui_schema_json`. The system supports forward and **server-side pre-generated reversed** playback with intelligent preloading.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       Transition Architecture                     │
+│                                                                   │
+│  ┌─────────────────────────────────────────────────────────────┐ │
+│  │                    Data Layer                                │ │
+│  │  tour_pages.ui_schema_json → elements[].transitionVideoUrl  │ │
+│  │  asset_variants.variant_type = 'reversed'                   │ │
+│  └─────────────────────────────────────────────────────────────┘ │
+│                              │                                    │
+│  ┌─────────────────────────────────────────────────────────────┐ │
+│  │                 Server Processing Layer                      │ │
+│  │  TourPagesService → videoProcessing.ts (FFmpeg reversal)    │ │
+│  └─────────────────────────────────────────────────────────────┘ │
+│                              │                                    │
+│  ┌─────────────────────────────────────────────────────────────┐ │
+│  │                   Execution Layer                            │ │
+│  │  Runtime Navigation │ Transition Overlay │ useTransitionPlayback│
+│  └─────────────────────────────────────────────────────────────┘ │
+│                              │                                    │
+│  ┌─────────────────────────────────────────────────────────────┐ │
+│  │                   Preloading Layer                           │ │
+│  │  usePreloadOrchestrator │ usePageSwitch │ useNeighborGraph  │ │
+│  │  getReadyBlobUrl │ S3 Presigned URLs │ Cache API            │ │
+│  └─────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Reverse Video Architecture
+
+### Server-Side Pre-Generated Reversed Variants
+
+The platform uses **server-side pre-computation** of reversed videos stored as separate asset variants. This approach was chosen over client-side frame-stepping for:
+
+- **Instant playback** - No client-side processing needed
+- **Device independence** - Works equally well on all devices
+- **Professional quality** - FFmpeg ensures perfect audio/video synchronization
+- **Reliability** - Pre-generated videos eliminate runtime failures
+
+### Reverse Generation Flow
+
+```
+Page Save Event (create/update)
+    ↓
+TourPagesService.update() / create()
+    ↓
+processReversedVideosAndUpdateSchema()
+    └─ For each navigation element with transitionVideoUrl:
+        ↓
+    getOrGenerateReversedVariant()
+        ├─ Check if reversed variant exists in asset_variants
+        └─ If not:
+            ↓
+        generateReversedVariant()
+            ├─ Download original video (downloadToBuffer)
+            ├─ Reverse with FFmpeg (videoProcessing.reverseVideo)
+            ├─ Upload reversed variant (uploadBuffer)
+            └─ Create asset_variants record with type='reversed'
+        ↓
+    Update ui_schema_json with reverseVideoUrl
+    ↓
+Save page with updated URLs
+```
+
+### Back Navigation Behavior
+
+Back navigation **always uses history mode** - when the user clicks a back button, they return to the previous page using the original forward transition played in reverse.
+
+**How it works:**
+1. User navigates forward from Page A to Page B (forward transition plays)
+2. User clicks back button on Page B
+3. System finds the forward navigation element that brought the user from Page A
+4. The reversed video from that forward element plays
+5. User returns to Page A
+
+**Benefits:**
+- Simpler UX - back button works like browser back
+- No configuration needed - back navigation is automatic
+- Consistent behavior - same transition forward and back
+
+## Data Model
+
+### Transition Configuration in Elements
+
+Transition settings are stored directly on navigation elements:
+
+```typescript
+// In tour_pages.ui_schema_json.elements
+{
+  id: "nav-button-1",
+  type: "navigation_next",
+  label: "Next Page",
+
+  // Navigation target
+  targetPageSlug: "gallery-page",
+
+  // Transition configuration
+  transitionVideoUrl: "assets/project-xyz/transitions/zoom-in.mp4",
+  transitionDurationSec: 2.5,
+  transitionReverseMode: "auto_reverse",  // or "separate_video"
+  reverseVideoUrl: undefined,              // Auto-populated by server on save
+
+  // Position & styling
+  xPercent: 90,
+  yPercent: 85,
+  iconUrl: "assets/icons/arrow.png"
+}
+```
+
+### Key Transition Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `transitionVideoUrl` | string | URL to transition video asset |
+| `transitionDurationSec` | number | Duration in seconds (auto-detected from video metadata) |
+| `transitionReverseMode` | `'auto_reverse'` \| `'separate_video'` | How back navigation transitions should play |
+| `reverseVideoUrl` | string | **Auto-generated** reversed video URL (or manually uploaded for `separate_video` mode) |
+
+**Reverse Mode Options:**
+| Mode | Behavior |
+|------|----------|
+| `auto_reverse` | Server generates reversed video on page save |
+| `separate_video` | Uses manually uploaded `reverseVideoUrl` for back navigation |
+| _(omitted)_ | No transition on back navigation |
+
+### Database Schema
+
+**asset_variants table** (stores reversed videos):
+
+```sql
+-- Variant types enum includes 'reversed'
+ALTER TYPE enum_asset_variants_variant_type ADD VALUE 'reversed';
+
+-- Columns for reversed variants
+assetId: UUID          -- Parent asset reference
+variant_type: 'reversed'
+cdn_url: TEXT          -- Public URL (S3/GCloud/local)
+storage_key: TEXT      -- Private storage path
+size_mb: DECIMAL       -- File size
+```
+
+**Storage path pattern:** `assets/${assetId}/reversed.mp4`
+
+### Benefits of Inline Storage
+
+1. **Simpler data model** - No separate transitions table to manage
+2. **No ID remapping** - Videos are referenced by URL, not foreign key
+3. **Per-element transitions** - Different navigation buttons can have different transitions
+4. **Easy publishing** - Transitions copy with the page, no extra steps needed
+5. **Automatic reversal** - Server generates reversed videos on page save
+
+## Server Requirements
+
+### FFmpeg Runtime
+
+FFmpeg is **required** for reversed video generation. Without it, back
+navigation transitions won't have pre-generated reversed videos.
+
+The project uses bundled FFmpeg binaries through the backend npm packages
+`ffmpeg-static` and `ffprobe-static`. Manual OS-level installation is not
+required for the standard setup.
+
+**Verify bundled runtime from the backend context:**
+
+```bash
+cd backend
+node -e "console.log(require('ffmpeg-static')); console.log(require('ffprobe-static').path)"
+```
+
+### VM Memory Risk
+
+Reverse generation can be memory-heavy. On the standard VM, a June 2026
+incident was caused by the kernel OOM-killing an `ffmpeg` child process that
+used about 3.3 GiB RSS on a 3.8 GiB RAM VM. Because the child process belonged
+to the PM2 systemd unit, PM2 stopped the frontend, backend, executor, and
+telemetry processes, causing Apache to return `503 Service Unavailable`.
+
+See [deployment-vm.md](deployment-vm.md) for the VM recovery runbook.
+
+Implemented resource controls:
+
+1. `videoProcessing.reverseVideo()` uses an in-process single-worker queue, so
+   only one FFmpeg reversal runs at a time. Additional requests wait for the
+   previous job to finish.
+2. FFmpeg reversal uses `-threads 1` to reduce CPU and memory pressure.
+3. FFmpeg reversal has a hard timeout (`FFMPEG_REVERSE_TIMEOUT_MS`, default
+   `600000`, exposed as `config.resilience.ffmpeg.reverseTimeoutMs`) and kills
+   the child process when the timeout is reached.
+4. FFmpeg reversal is protected by an in-process circuit breaker
+   (`FFMPEG_BREAKER_FAILURE_THRESHOLD`, `FFMPEG_BREAKER_COOLDOWN_MS`,
+   `FFMPEG_BREAKER_SUCCESS_THRESHOLD`, exposed under
+   `config.resilience.ffmpeg.breaker`) so repeated failures stop new reversal
+   jobs during the cooldown window.
+5. FFprobe metadata extraction has a timeout (`FFPROBE_TIMEOUT_MS`, default
+   `30000`, exposed as `config.resilience.ffmpeg.ffprobeTimeoutMs`), and
+   reverse-video logs include input/output byte sizes plus probed media
+   metadata.
+6. External file storage calls used by reversal download/upload paths are
+   protected by the shared file-storage circuit breaker for S3/GCloud providers.
+7. `TourPagesService` still deduplicates generation by transition video
+   `storageKey`, so repeated requests for the same source video share the same
+   generation promise.
+8. Before enqueueing auto-reverse generation, `TourPagesService` validates the
+   source asset in one place. It rejects transition videos larger than `16 GiB`
+   unless a reversed variant already exists, and it also rejects videos whose
+   stored `width_px`, `height_px`, `duration_sec`, and `frame_rate` imply too
+   much decoded frame data for the VM. Asset `frame_rate` is now probed on the
+   backend with bundled `ffprobe-static` during asset create/update. For older
+   assets without persisted `frame_rate`, the validation path probes the stored
+   file on demand and only falls back to a conservative `30 FPS` estimate if
+   probing fails.
+9. The page save returns a validation error so the constructor can show an
+   explicit user-facing notification instead of silently starting a risky
+   background job.
+
+Additional hardening still recommended:
+
+1. Reject or downscale very large transition videos before reversal.
+2. Consider running media processing in a separate worker with memory limits.
+
+## Backend Implementation
+
+### Video Processing Service
+
+**File:** `backend/src/services/videoProcessing.ts`
+
+FFmpeg-based video reversal:
+
+```typescript
+import { isFFmpegAvailable, reverseVideo } from './videoProcessing.ts';
+
+// Core function: reverseVideo(inputBuffer, filename) → reversedBuffer
+// Processing pipeline:
+//   1. Create temporary directory for FFmpeg operations
+//   2. Write input buffer to temp file
+//   3. Probe input media metadata with a timeout
+//   4. Execute FFmpeg behind the single-worker queue and circuit breaker:
+//      - -vf reverse (video reversal)
+//      - -af areverse (audio reversal)
+//      - -c:v libx264 (H.264 encoding)
+//      - -preset fast (performance preset)
+//      - -crf 23 (compression quality)
+//      - -c:a aac (audio encoding)
+//      - -threads 1 (resource cap)
+//      - kill FFmpeg if FFMPEG_REVERSE_TIMEOUT_MS is exceeded
+//   5. Probe output media metadata and log input/output sizes
+//   6. Read output buffer
+//   7. Clean up temporary files
+```
+
+### Tour Pages Service Integration
+
+**File:** `backend/src/services/tour_pages.ts`
+
+Key functions:
+- `processReversedVideosAndUpdateSchema()` - Main orchestrator for reverse generation
+- `getOrGenerateReversedVariant()` - Check/generate reversed variant
+- `generateReversedVariant()` - Download → Reverse → Upload → Record
+- `regenerateProjectReversedVideos()` - Project-wide generation for missing reversed videos
+
+**Generation Pattern:**
+- Reversed videos are always generated for all navigation elements with transitions
+- Generated on-demand when page is saved (create/update)
+- Checked before generation to avoid duplication
+- Different transition videos are processed sequentially through the global
+  FFmpeg queue; the backend does not run multiple FFmpeg reversals in parallel
+- Background processing keeps save requests fast
+
+### File Service Integration
+
+**File:** `backend/src/services/file.ts`
+
+Key functions used for reverse generation:
+- `downloadToBuffer(privateUrl)` - Downloads file from storage provider to Buffer
+- `uploadBuffer(privateUrl, buffer, options)` - Uploads buffer to storage
+
+## Frontend Types
+
+**File:** `frontend/src/types/constructor.ts`
+
+```typescript
+interface CanvasElement {
+  id: string;
+  type: CanvasElementType;  // 'navigation_next' | 'navigation_prev' | ...
+  label: string;
+
+  // Navigation
+  targetPageSlug?: string;
+  /** @deprecated Use targetPageSlug instead */
+  targetPageId?: string;
+
+  // Transition
+  transitionVideoUrl?: string;
+  transitionDurationSec?: number;
+  transitionReverseMode?: 'auto_reverse' | 'separate_video';
+  reverseVideoUrl?: string;  // Auto-generated or manually uploaded
+
+  // ... other fields
+}
+```
+
+**File:** `frontend/src/types/presentation.ts`
+
+```typescript
+// Shared presentation types for RuntimePresentation and constructor.tsx
+
+// Canvas element with navigation properties (for click handling)
+interface NavigableElement {
+  id: string;
+  type: string;
+  targetPageSlug?: string;
+  targetPageId?: string;
+  transitionVideoUrl?: string;
+  reverseVideoUrl?: string;
+  navType?: 'forward' | 'back';
+  navDisabled?: boolean;
+}
+
+// Navigation target resolved from element click
+interface NavigationTarget {
+  page: RuntimePage;
+  pageId: string;
+  transitionVideoUrl?: string;
+  reverseVideoUrl?: string;
+  isBack: boolean;
+}
+
+// Transition phase (exported for navigation helpers)
+type TransitionPhase = 'idle' | 'preparing' | 'playing' | 'finishing' | 'completed';
+```
+
+**File:** `frontend/src/hooks/useTransitionPlayback.ts`
+
+```typescript
+// ReverseMode for transition playback (runtime)
+type ReverseMode = 'none' | 'separate';  // 'reverse' removed - now uses pre-generated videos
+
+interface TransitionConfig {
+  videoUrl: string;
+  storageKey?: string;        // Raw storage path for cache lookup
+  reverseMode: ReverseMode;
+  reverseVideoUrl?: string;   // Pre-generated reversed video URL
+  reverseStorageKey?: string; // Storage key for reversed video
+  durationSec?: number;
+  targetPageId?: string;
+  displayName?: string;
+  isBack?: boolean;           // Track navigation direction
+}
+
+// Internal playback phases
+type PlaybackPhase = 'idle' | 'preparing' | 'playing' | 'finishing' | 'completed';
+```
+
+**Mapping between constructor and runtime modes:**
+| Constructor (`transitionReverseMode`) | Runtime (`ReverseMode`) |
+|---------------------------------------|-------------------------|
+| `'auto_reverse'` | `'separate'` (uses pre-generated `reverseVideoUrl`) |
+| `'separate_video'` | `'separate'` |
+| _(omitted)_ | `'none'` |
+
+## Runtime Execution
+
+### Navigation Flow
+
+**File:** `frontend/src/components/RuntimePresentation.tsx`
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  1. User clicks navigation element                           │
+│     └── handleElementClick(element)                          │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  2. Resolve target page from slug                            │
+│     └── pages.find(p => p.slug === element.targetPageSlug)   │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  3. Check for transition video                               │
+│     └── element.transitionVideoUrl exists?                   │
+└──────────────────────────────────────────────────────────────┘
+                              │
+          ┌───────────────────┴───────────────────┐
+          │ Yes                                   │ No
+          ▼                                       ▼
+┌──────────────────────┐              ┌──────────────────────┐
+│  4a. Set transition  │              │  4b. Direct navigate │
+│  state with correct  │              │  to target page      │
+│  video URL           │              │                      │
+│                      │              │  setSelectedPageId() │
+│  isBack?             │              └──────────────────────┘
+│  ├─ true: use        │
+│  │  reverseVideoUrl  │
+│  └─ false: use       │
+│     transitionVideoUrl│
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────────────────────┐
+│  5. Render full-screen video overlay                         │
+│                                                              │
+│  Forward: video.play() with transitionVideoUrl              │
+│  Back: video.play() with reverseVideoUrl (pre-generated)    │
+└──────────────────────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────────────────────┐
+│  6. Video ends (or fallback timeout fires)                   │
+│     └── finishOverlayTransition()                            │
+│     └── applyPageSelection(targetPageId)                     │
+│     └── Clear overlay state                                  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Source URL Selection
+
+**File:** `frontend/src/hooks/useTransitionPlayback.ts`
+
+```typescript
+const sourceUrl = useMemo(() => {
+  if (!transition) return '';
+  // Use reversed video if back navigation with separate reversed video
+  if (transition.isBack && transition.reverseVideoUrl) {
+    return transition.reverseVideoUrl;
+  }
+  return transition.videoUrl;
+}, [transition]);
+```
+
+**Key Characteristics:**
+- No frame-stepping computation needed
+- Simple conditional: if back navigation AND reversed URL exists → use reversed video
+- Direct playback from downloaded buffer
+
+### Transition Preview Hook
+
+**File:** `frontend/src/hooks/useTransitionPreview.ts`
+
+```typescript
+// Validation before preview
+if (direction === 'back' && !element.reverseVideoUrl) {
+  onError?.('Reversed video not available. Save the page to generate it.');
+  return;
+}
+
+// Preview state structure
+{
+  videoUrl: element.transitionVideoUrl,
+  reverseMode: direction === 'back' ? 'separate' : 'none',
+  reverseVideoUrl: element.reverseVideoUrl,    // Pre-reversed video URL
+  reverseStorageKey: element.reverseVideoUrl,  // Storage path for caching
+  isBack: direction === 'back'                 // Track navigation direction
+}
+```
+
+### Overlay Rendering
+
+**File:** `frontend/src/components/Constructor/TransitionPreviewOverlay.tsx`
+
+The `TransitionPreviewOverlay` component renders transition videos within the letterboxed canvas bounds:
+
+```tsx
+<TransitionPreviewOverlay
+  videoRef={transitionVideoRef}
+  isActive={Boolean(transitionPreview)}
+  isBuffering={transitionPhase === 'preparing' || isBuffering}
+  letterboxStyles={letterboxStyles}  // From useCanvasScale hook
+  opacity={1}  // Always 1 - no fade-out for video transitions
+/>
+```
+
+**Component Props:**
+| Prop | Type | Description |
+|------|------|-------------|
+| `videoRef` | `RefObject<HTMLVideoElement>` | Reference managed by `useTransitionPlayback` |
+| `isActive` | `boolean` | Whether overlay is visible |
+| `isBuffering` | `boolean` | **Hides entire container** while buffering (prevents black flash) |
+| `letterboxStyles` | `CSSProperties` | Position/size from `useCanvasScale` |
+| `videoFit` | `'contain'` \| `'cover'` | Object-fit mode (default: `'contain'`) |
+| `opacity` | `number` | Container opacity (default: 1) |
+
+**Video Transition Flow (No Fades):**
+```
+1. Click → isBuffering=true → container opacity=0 (old page visible)
+2. Video ready → isBuffering=false → container opacity=1 (video first frame)
+3. Video plays → last frame = new page background
+4. onComplete → setTransitionPreview(null) → instant overlay removal
+```
+
+**Key Design Decision:**
+- Video transitions do NOT use fade effects
+- Video itself IS the transition (first frame = old page, last frame = new page)
+- Overlay removed instantly when new background is ready
+- This prevents any visual discontinuity
+
+### Navigation Helpers
+
+**File:** `frontend/src/lib/navigationHelpers.ts`
+
+Shared utilities for page navigation:
+
+```typescript
+import {
+  resolveNavigationTarget,
+  isBackNavigation,
+  getNavigationDirection,
+  isTransitionBlocking,
+  hasPlayableTransition,
+  isNavigationType,
+} from '../lib/navigationHelpers';
+```
+
+| Function | Purpose |
+|----------|---------|
+| `resolveNavigationTarget(element, pages, context)` | Resolve target page from element. Back navigation always uses history mode |
+| `isBackNavigation(element)` | Check if element navigates backwards |
+| `getNavigationDirection(element)` | Get navigation direction as `'back'` or `'forward'` |
+| `isTransitionBlocking(transitionPhase)` | Check if transition is blocking navigation |
+| `hasPlayableTransition(element, direction)` | Check if element has playable transition |
+| `isNavigationType(elementType)` | Check if element type is a navigation type |
+| `resolveHistoryBackTarget(pages, currentSlug, previousPageId)` | Resolve back target from navigation history |
+| `findIncomingNavigationElement(pages, fromPageId, toPageId)` | Find forward element that links pages |
+
+**Playable Transition Check:**
+
+```typescript
+const hasPlayableTransition = (
+  element: {
+    transitionVideoUrl?: string;
+    transitionReverseMode?: string;
+    reverseVideoUrl?: string;
+  },
+  direction: 'back' | 'forward' = 'forward',
+): boolean => {
+  if (!element.transitionVideoUrl) return false;
+
+  // For back navigation, need reverse video (auto-generated or separate)
+  if (direction === 'back' && !element.reverseVideoUrl) {
+    return false;
+  }
+
+  return true;
+};
+```
+
+## Constructor Configuration
+
+### Setting Up Transitions
+
+**File:** `frontend/src/pages/constructor.tsx`
+
+When editing a navigation element:
+
+1. Select element type (`navigation_next` or `navigation_prev`)
+2. Choose target page by slug
+3. Select transition video from project assets
+4. Duration is auto-detected from video metadata
+5. Choose reverse mode for back navigation
+6. **Save the page** to trigger reverse video generation
+
+```typescript
+// Saving navigation element with transition
+const elementData = {
+  type: selectedElementType,
+  targetPageSlug: targetPage?.slug,
+  transitionVideoUrl: selectedTransitionVideo?.cdn_url,
+  transitionDurationSec: transitionDuration,
+  transitionReverseMode: reverseMode,  // 'auto_reverse' | 'separate_video' | undefined
+  reverseVideoUrl: reverseMode === 'separate_video' ? reverseVideo?.cdn_url : undefined,
+  // Note: reverseVideoUrl is auto-populated for 'auto_reverse' mode on save
+};
+```
+
+**Reverse Mode UI Options:**
+
+| UI Option | `transitionReverseMode` | `reverseVideoUrl` |
+|-----------|-------------------------|-------------------|
+| "Auto Reverse" | `'auto_reverse'` | **Auto-generated on save** |
+| "Separate Video" | `'separate_video'` | User-uploaded video |
+| "No Reverse" | _(not set)_ | _(not set)_ |
+
+### When to Enable Reverse
+
+| Video Type | `transitionReverseMode` | Reason |
+|------------|-------------------------|--------|
+| Zoom in/out | `'auto_reverse'` | Symmetrical animation |
+| Slide left/right | `'auto_reverse'` | Direction can reverse |
+| Fade in/out | `'auto_reverse'` | Works both directions |
+| Text animation | `'separate_video'` | Use dedicated reverse video |
+| One-way motion | _(omit)_ | Only makes sense forward |
+| Complex animation | `'separate_video'` | Pre-rendered reverse looks better |
+
+## Preloading Integration
+
+### Transition Video Preloading
+
+**File:** `frontend/src/lib/extractPageLinks.ts`
+
+Transition videos (including reversed) are extracted from navigation elements:
+
+```typescript
+import { extractPageLinksAndElements } from '../lib/extractPageLinks';
+
+// Extract navigation links (includes transition and reverse videos)
+const { pageLinks, preloadElements } = extractPageLinksAndElements(filteredPages);
+
+// pageLinks contains transition information:
+// { from_pageId, to_pageId, transition: { video_url, reverse_video_url } }
+```
+
+### Priority Calculation
+
+Transition videos have the **highest priority** (+150):
+
+```
+Transition Priority = neighborBase + assetTypeBonus
+
+neighborBase: 1000 (current page) or 500 (neighbor)
+assetTypeBonus: 150 (transition - highest priority)
+
+Examples:
+- Current page transition: 1000 + 150 = 1150
+- Neighbor (depth 1) transition: 500 + 150 = 650
+```
+
+**Asset Type Priorities:**
+| Type | Priority | Reason |
+|------|----------|--------|
+| Transition | +150 | Needed immediately on click |
+| Image | +100 | Required for page display |
+| Audio | +50 | Background audio |
+| Video | +30 | Can stream progressively |
+
+### Sophisticated Source Resolution Pipeline
+
+**File:** `frontend/src/hooks/useTransitionPlayback.ts`
+
+```typescript
+// Source resolution order:
+1. Try storage key ready blob URL (pre-downloaded)
+2. Try storage key cached blob URL (Cache API)
+3. Reuse cached blob URL from previous playback
+4. Try ready blob URL by resolved CDN URL
+5. Try cached blob URL by resolved CDN URL
+6. Fetch video as blob with presigned URL or proxy fallback
+```
+
+**Storage Key Usage:**
+- `storageKey` and `reverseStorageKey` used for cache lookup
+- Allows offline access via IndexedDB
+- Distinguishes between original and reversed video caches
+
+## Non-Transition Navigation (CSS Transitions)
+
+When navigating without a video transition, the system uses CSS-based transitions with settings resolved through a cascade.
+
+### Settings Cascade Resolution
+
+Transition settings (type, duration, easing, overlay color) are resolved through a three-level cascade:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Transition Settings Cascade                           │
+│                                                                          │
+│  1. Element Level (highest priority)                                    │
+│     └── ui_schema_json.elements[].transitionSettings                    │
+│                              ↓ fallback                                  │
+│  2. Project Level (per environment)                                     │
+│     └── project_transition_settings WHERE projectId AND environment     │
+│                              ↓ fallback                                  │
+│  3. Global Level (platform-wide defaults)                               │
+│     └── global_transition_defaults (single record)                      │
+│                              ↓ fallback                                  │
+│  4. Hardcoded Fallback                                                  │
+│     └── type: 'fade', durationMs: 700, easing: 'ease-in-out'           │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Hook:** `useTransitionSettings` resolves final settings:
+
+```typescript
+const transitionSettings = useTransitionSettings({
+  globalDefaults,      // From global_transition_defaults table
+  projectSettings,     // From project_transition_settings (environment-specific)
+  elementSettings,     // From currentElementTransitionSettings state
+});
+
+// Returns: { type, durationMs, easing, overlayColor }
+```
+
+**Extracting element settings:** Use `extractElementTransitionSettings()` to convert element fields:
+
+```typescript
+import { extractElementTransitionSettings } from '../types/transition';
+
+// Extract from clicked navigation element
+const elementSettings = extractElementTransitionSettings(clickedElement);
+// Returns: { transitionType?, transitionDurationMs?, transitionEasing?, transitionOverlayColor? }
+```
+
+The function only includes fields with actual values (not empty strings), allowing cascade fallthrough when element uses "Use Project Default".
+
+**Environment-Aware Project Settings:**
+
+Project transition settings are stored per-environment and copied during publishing:
+- **Constructor** (dev): Edits `project_transition_settings WHERE environment='dev'`
+- **Save to Stage**: Copies dev settings → stage
+- **Publish**: Copies stage settings → production
+
+See [project-transition-settings.md](./project-transition-settings.md) for full documentation.
+
+### CSS Transition Implementation
+
+**CSS Variables (main.css) - Single Source of Truth:**
+```css
+:root {
+  --crossfade-duration: 700ms;
+  /* Smooth easing: slow start, gentle acceleration, soft landing */
+  --crossfade-easing: cubic-bezier(0.4, 0, 0.2, 1);
+}
+```
+
+**CSS Animations (main.css):**
+```css
+@keyframes page-crossfade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes page-crossfade-out {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}
+
+.animate-crossfade-in {
+  animation: page-crossfade-in var(--crossfade-duration, 700ms) var(--crossfade-easing, cubic-bezier(0.4, 0, 0.2, 1)) forwards;
+}
+
+.animate-crossfade-out {
+  animation: page-crossfade-out var(--crossfade-duration, 700ms) var(--crossfade-easing, cubic-bezier(0.4, 0, 0.2, 1)) forwards;
+}
+```
+
+**Easing Curve Characteristics:**
+- `cubic-bezier(0.4, 0, 0.2, 1)` - Material Design standard easing
+- Slow start - prevents abrupt appearance
+- Gentle acceleration through middle
+- Soft landing at end
+
+### CSS Transition vs Video Transition
+
+| Navigation Type | Effect | Duration Control | Settings Source |
+|-----------------|--------|------------------|-----------------|
+| With transition video | Video overlay plays, instant removal | Video duration | Element-level only |
+| Without transition video | CSS fade animation | Cascade resolution | Element → Project → Global |
+
+## File References
+
+| File | Purpose |
+|------|---------|
+| `backend/src/services/videoProcessing.ts` | FFmpeg video reversal service |
+| `backend/src/services/tour_pages.ts` | Reverse video generation orchestration |
+| `backend/src/services/file.ts` | Download/upload buffer operations |
+| `backend/src/services/project_transition_settings.ts` | Project transition settings service |
+| `backend/src/db/api/asset_variants.ts` | Reversed variant database operations |
+| `backend/src/db/api/project_transition_settings.ts` | Project transition settings API |
+| `backend/src/db/models/asset_variants.js` | Asset variants model (includes 'reversed' type) |
+| `backend/src/db/models/project_transition_settings.js` | Project transition settings model |
+| `backend/src/db/migrations/20260413091125-add-reversed-variant-type.js` | Migration for reversed variant support |
+| `backend/src/db/migrations/20260501000002-create-project-transition-settings.js` | Project transition settings table |
+| `frontend/src/css/main.css` | CSS animation keyframes and classes |
+| `frontend/src/pages/constructor.tsx` | Transition video selection UI |
+| `frontend/src/components/RuntimePresentation.tsx` | Transition overlay playback and navigation |
+| `frontend/src/components/TourFlowManager.tsx` | Project transition settings UI |
+| `frontend/src/components/Constructor/TransitionPreviewOverlay.tsx` | Canvas-aware transition video overlay |
+| `frontend/src/lib/extractPageLinks.ts` | Extract transition videos from navigation elements |
+| `frontend/src/lib/navigationHelpers.ts` | Navigation target resolution, reverse detection |
+| `frontend/src/stores/project_transition_settings/projectTransitionSettingsSlice.ts` | Redux store for transition settings |
+| `frontend/src/hooks/usePreloadOrchestrator.ts` | Preloading with ready blob URLs |
+| `frontend/src/hooks/usePageSwitch.ts` | Page navigation using preloaded transitions |
+| `frontend/src/hooks/useTransitionPlayback.ts` | Transition video playback coordination |
+| `frontend/src/hooks/useTransitionPreview.ts` | Transition preview with reverse validation |
+| `frontend/src/hooks/useTransitionSettings.ts` | Cascade resolution for transition settings |
+| `frontend/src/hooks/useBackgroundTransition.ts` | Background fade-out coordination |
+| `frontend/src/hooks/useNeighborGraph.ts` | Navigation graph for preload prioritization |
+| `frontend/src/types/constructor.ts` | Element type definitions |
+| `frontend/src/types/transition.ts` | Transition settings types |
+| `frontend/src/types/presentation.ts` | Runtime navigation types |
+| `frontend/src/config/preload.config.ts` | Preload priority weights |
+
+## Error Handling
+
+### Video Load Failures
+
+```typescript
+videoRef.current.onerror = (e) => {
+  console.error('Transition video failed to load:', e);
+  // Fallback: complete navigation without video
+  finishOverlayTransition();
+};
+```
+
+### Missing Reversed Video
+
+```typescript
+// In useTransitionPreview
+if (direction === 'back' && !element.reverseVideoUrl) {
+  onError?.('Reversed video not available. Save the page to generate it.');
+  return;
+}
+```
+
+### FFmpeg Unavailable
+
+```typescript
+// In videoProcessing.ts
+if (!isFFmpegAvailable()) {
+  logger.warn('FFmpeg not available, skipping reverse video generation');
+  return null;
+}
+```
+
+## Environment Handling
+
+Transitions are environment-aware:
+
+```typescript
+// Pages are filtered by environment before extraction
+const filteredPages = pages.filter(p => p.environment === environment);
+
+// Transitions only work between pages in the same environment
+const { pageLinks } = extractPageLinksAndElements(filteredPages);
+```
+
+| Environment | Context | Access |
+|-------------|---------|--------|
+| `dev` | Constructor editing | Authenticated |
+| `stage` | Preview/review | Authenticated |
+| `production` | Public runtime | Public |
+
+**Publishing:** When pages are published (dev → stage → production), transitions and reversed videos are copied as part of `ui_schema_json`. Since transitions reference video URLs (not IDs), no remapping is needed.
+
+## Performance Considerations
+
+### 1. Server-Side Generation Benefits
+
+| Aspect | Client-Side (Old) | Server-Side (New) |
+|--------|-------------------|-------------------|
+| Computation | During playback | At page save time |
+| Device Performance | Device-dependent | Instant playback |
+| Audio Sync | Manual filtering | FFmpeg perfect sync |
+| Memory Usage | High during playback | None (pre-generated) |
+
+### 2. Video Format
+
+Use optimized video formats:
+- MP4 with H.264 for broad compatibility
+- WebM with VP9 for better compression
+- Keep transitions short (0.5-3 seconds)
+
+### 3. Caching Strategy
+
+| Layer | Purpose |
+|-------|---------|
+| Cache API (< 5MB) | Fast asset storage |
+| IndexedDB (≥ 5MB) | Large assets, offline data |
+| Blob URLs | Pre-decoded for instant display |
+
+## Troubleshooting
+
+### Transition Doesn't Play
+1. Check `transitionVideoUrl` is valid
+2. Verify video is in supported format
+3. Check browser console for CORS errors
+4. Ensure video is preloaded (check Network tab)
+
+### Reverse Video Not Available
+1. **Save the page** - reverse videos are generated on page save
+2. Check server logs for FFmpeg errors
+3. Verify bundled FFmpeg paths resolve from the backend process
+4. Check `asset_variants` table for `variant_type='reversed'` records
+5. On the VM, check kernel logs for OOM-killed `ffmpeg` processes
+
+### Back Navigation Has No Transition
+1. Verify `transitionReverseMode` is set (`'auto_reverse'` or `'separate_video'`)
+2. For `'auto_reverse'`: save the page to trigger generation
+3. For `'separate_video'`: ensure `reverseVideoUrl` is set
+4. Check `hasPlayableTransition(element, 'back')` returns true
+
+### Navigation Gets Stuck
+1. Check fallback timeout is firing
+2. Verify `onEnded` event triggers
+3. Look for JavaScript errors
+4. Check transition state clears properly
+
+### Element Settings Not Applied (Wrong Duration/Easing)
+
+**Symptom:** Element-level transition settings (duration, easing, overlay color) are ignored; transition uses project or global defaults instead.
+
+**Cause:** React's async state batching. When clicking a navigation button:
+1. `setCurrentElementTransitionSettings()` schedules state update
+2. `switchToPage()` starts transition immediately
+3. `useTransitionSettings` resolves with OLD state (before React processes step 1)
+
+**Solution:** Use `flushSync` from `react-dom` to force synchronous state updates:
+
+```typescript
+import { flushSync } from 'react-dom';
+import { extractElementTransitionSettings } from '../types/transition';
+
+// In handleElementClick:
+const elementSettings = extractElementTransitionSettings(clickedElement);
+
+// Force synchronous update BEFORE navigation
+flushSync(() => {
+  setCurrentElementTransitionSettings(elementSettings);
+});
+
+// Now transition uses correct element settings
+switchToPage(targetPageId, config);
+```
+
+**Files requiring this fix:**
+- `frontend/src/pages/constructor.tsx`
+- `frontend/src/components/RuntimePresentation.tsx`
+
+**Debug tip:** Add console.log inside `useTransitionSettings` to verify element settings are received:
+```typescript
+console.log('[useTransitionSettings] element:', elementSettings);
+```
+If element shows as `null` when it shouldn't, the flushSync fix is missing.
diff --git a/documentation/private-production-presentations.md b/documentation/private-production-presentations.md
new file mode 100644
index 0000000..8c4af16
--- /dev/null
+++ b/documentation/private-production-presentations.md
@@ -0,0 +1,143 @@
+# Private Production Presentations
+
+Production presentations are public by default at `/p/[slug]`. Each project can
+switch its production presentation to private with the project-level
+`production_presentation_visibility` field.
+
+## Project Visibility
+
+**Storage:** `projects.production_presentation_visibility`
+
+Values:
+
+- `public` - default; anonymous users can open `/p/[slug]`
+- `private` - anonymous users must log in; access is then checked by staff
+  permissions or customer grants
+
+The project create/edit forms expose this as **Production Presentation
+Visibility**. Existing projects stay public after migration for backward
+compatibility.
+
+## Customer Access Grants
+
+**Storage:** `production_presentation_access`
+
+This table grants a customer user access to a private production presentation:
+
+- `projectId`
+- `userId`
+- unique active pair: `(projectId, userId)`
+
+User lifecycle remains in the existing users system. Presentation access is
+stored in DB rows, not config files.
+
+## Runtime Access Flow
+
+**Services:**
+
+- `backend/src/services/runtime-presentation-access.ts` handles slug lookup and
+  private-presentation listing.
+- `backend/src/services/access-policy.ts` owns the final access decision through
+  `canViewProductionPresentation(user, projectSlug)`.
+
+The service determines:
+
+- whether the project slug points to a private production presentation
+- whether an authenticated user can use admin APIs (`Public` users are never
+  treated as staff, even if stale permissions exist)
+- whether a customer user has a `production_presentation_access` row
+- which private production slugs are allowed for the current customer user
+
+For public production slugs, read-only runtime requests stay public.
+
+For private production slugs:
+
+- anonymous `GET` requests return `401`
+- authenticated users with any RBAC permission can access all private
+  production presentations as platform staff
+- authenticated users with `Public` role and no permissions must have an access
+  row for the project
+- authenticated but unauthorized users receive `403`
+- authorized users are marked as `req.isRuntimePublicRequest = true` so runtime
+  routes return only runtime-safe entity fields
+
+Protected runtime data includes:
+
+- `/api/projects`
+- `/api/tour_pages`
+- `/api/project_audio_tracks`
+- `/api/project-transition-settings/project/:projectId/env/production`
+
+## User Creation And Edit Flow
+
+`Administrator`, `Platform Owner`, and `Account Manager` can create users and
+edit existing users.
+
+When the selected role is `Public`, the user form shows **Allowed
+Private Production Presentations**. The selector lists only projects whose
+production presentation visibility is `private`.
+
+On create submit:
+
+- the user is created normally
+- if the selected role is `Public`, selected private project IDs create
+  `production_presentation_access` rows
+- if the selected role is not `Public`, selected project IDs are ignored
+
+On edit submit:
+
+- existing `production_presentation_access` rows for that user are replaced by
+  the selected private project IDs
+- switching a user away from `Public` clears their private presentation grants
+- loading a Public user edit form preselects the user's current private
+  presentation grants
+
+Do not grant customer viewer users broad app permissions such as
+`READ_PROJECTS` or `READ_TOUR_PAGES`; any RBAC permission makes the user
+platform staff for private presentation access.
+
+Backend hardening also rejects custom permissions for users whose role is
+`Public`, rejects permissions assigned to the `Public` role through the Roles
+service, and ignores `Public` user or role-fallback permissions in
+`AccessPolicy` for admin APIs.
+
+## Audit And Cleanup
+
+Use the backend audit command to detect stale access records from older data:
+
+```bash
+cd backend
+npm run check:public-access
+```
+
+It reports:
+
+- RBAC permissions assigned to roles named `Public`
+- custom permissions assigned to Public users
+- private production presentation grants assigned to non-Public users
+
+To clean those stale records after reviewing the output:
+
+```bash
+npm run fix:public-access
+```
+
+The fix removes only the stale Public-role permissions, Public-user custom
+permissions, and non-Public private presentation grants.
+
+## Frontend Behavior
+
+If runtime data loading receives `401`, `/p/[slug]` redirects to:
+
+```text
+/login?next=/p/[slug]
+```
+
+After login, `login.tsx` redirects to `next` when it is a safe local path. If a
+Public customer user reaches authenticated application pages,
+`LayoutAuthenticated` redirects to the first private production slug returned by
+`/api/auth/me`; if the Public user has no private presentation grants, it
+redirects to `/`.
+
+Public production presentations remain accessible to anonymous users, platform
+staff, and logged-in customer users.
diff --git a/documentation/project-architecture.md b/documentation/project-architecture.md
new file mode 100644
index 0000000..f6e41e3
--- /dev/null
+++ b/documentation/project-architecture.md
@@ -0,0 +1,1052 @@
+# Project Architecture - E2E Documentation
+
+## Overview
+
+**Tour Builder Platform** - A sophisticated web application for building and managing virtual tours with interactive pages, assets, transitions, and offline capabilities.
+
+**Technology Stack:**
+- **Frontend**: Next.js 15 with React 19, TypeScript, Redux Toolkit, Tailwind CSS, Serwist PWA
+- **Backend**: Node.js/Express with Sequelize ORM
+- **Database**: PostgreSQL with migrations and seeders
+- **File Storage**: AWS S3 (configurable via `FILE_STORAGE_PROVIDER`)
+
+---
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Frontend                                 │
+│  Next.js 15 │ React 19 │ Redux Toolkit │ Tailwind │ Serwist    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                         HTTP/REST
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                         Backend                                  │
+│  Express.js │ Passport.js │ Sequelize ORM │ Factory Patterns    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                         Sequelize
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                        Database                                  │
+│  PostgreSQL │ Migrations │ Seeders                              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                      File Storage                                │
+│  AWS S3 │ Google Cloud Storage │ Local Filesystem               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Standard VM Deployment
+
+The standard Flatlogic VM adds Apache, PM2, and executor services around the
+application:
+
+```
+Cloudflare
+  -> Apache :80
+    -> Next.js frontend PM2 app `frontend-dev` :3001 (production server)
+    -> Express backend PM2 app `backend-dev` :3000 (NODE_ENV=dev_stage)
+
+PM2 systemd unit: pm2-ubuntu.service
+Auxiliary PM2 apps: fl-executor, fl-telemetry
+```
+
+Local development now mirrors this port split: frontend `3001`, backend
+`3000`. A protected backend endpoint returning `401 Unauthorized` is a healthy
+response when no JWT is supplied.
+
+For the detailed VM runbook, OOM recovery, process checks, and executor notes,
+see [deployment-vm.md](deployment-vm.md).
+
+---
+
+## Frontend Architecture
+
+### Directory Structure
+
+```
+frontend/src/
+├── pages/              # Next.js pages (dynamic routing)
+├── components/         # React components (PascalCase naming)
+├── stores/             # Redux Toolkit slices (entity-based)
+├── layouts/            # Page layouts (Authenticated, Guest)
+├── hooks/              # Custom React hooks (~32 hooks)
+├── lib/                # Utility libraries (offline, logging)
+├── types/              # TypeScript interfaces and types
+├── helpers/            # Utility functions
+├── css/                # Global CSS (Tailwind)
+├── config/             # App configuration
+├── context/            # React context providers
+├── schemas/            # Zod validation schemas
+└── factories/          # Page and component factories
+```
+
+### Pages Structure
+
+| Page Type | Pattern | Description |
+|-----------|---------|-------------|
+| List | `{entity}-list.tsx` | Data grid with CRUD, filtering, sorting |
+| Edit | `{entity}-edit.tsx` | Form-based entity modification |
+| View | `{entity}-view.tsx` | Read-only entity display |
+| New | `{entity}-new.tsx` | Create new entity form |
+
+**Special Pages:**
+- `constructor.tsx` - Visual tour builder (complex)
+- `p/[projectSlug]/index.tsx` - Production tour presentation
+- `p/[projectSlug]/stage.tsx` - Stage tour preview
+- `login.tsx` - Authentication page
+- `dashboard.tsx` - Overview and analytics
+
+### State Management (Redux Toolkit)
+
+**Store Configuration** (`stores/store.ts`):
+
+```typescript
+// Entity slices (13 total)
+users, roles, permissions, projects, assets, tour_pages,
+asset_variants, project_audio_tracks, publish_events, pwa_caches,
+access_logs, presigned_url_requests, project_memberships
+
+// Global slices
+authSlice      // Authentication state, JWT token
+mainSlice      // UI state, notifications
+styleSlice     // Theme, styling preferences
+```
+
+**Redux Pattern:**
+
+```typescript
+// Entity slice factory
+import { createEntitySlice } from './createEntitySlice';
+
+const assetsSlice = createEntitySlice('assets', {
+  // Custom reducers if needed
+});
+
+// Usage in components
+import { fetch, create, update, deleteItem } from '@/stores/assets/assetsSlice';
+import { useAppDispatch, useAppSelector } from '@/stores/hooks';
+
+const dispatch = useAppDispatch();
+const { rows, loading } = useAppSelector((state) => state.assets);
+
+dispatch(fetch({ query: '?limit=100&page=1' }));
+```
+
+### Component Organization
+
+```
+components/
+├── Assets/
+│   ├── AssetCard.tsx
+│   ├── AssetGrid.tsx
+│   ├── useAssetUploader.ts      # Custom hook
+│   └── ProjectSelector.tsx
+├── Offline/
+│   ├── OfflineToggle.tsx
+│   ├── OfflineStatusIndicator.tsx
+│   └── DownloadProgressPanel.tsx
+├── Layout/
+│   ├── Header.tsx
+│   ├── Sidebar.tsx
+│   └── Footer.tsx
+└── [Entity]/
+    ├── [Entity]Card.tsx
+    ├── [Entity]Form.tsx
+    └── [Entity]List.tsx
+```
+
+### Custom Hooks
+
+| Hook | Location | Purpose |
+|------|----------|---------|
+| `useAssetUploader` | `components/Assets/` | Chunked file upload management |
+| `usePreloadOrchestrator` | `hooks/` | Asset preloading with S3 presigned URLs and ready blob URLs |
+| `usePageSwitch` | `hooks/` | Smooth page navigation with preloaded blob URLs |
+| `useTransitionPlayback` | `hooks/` | Transition video playback coordination |
+| `useNeighborGraph` | `hooks/` | Navigation graph for preloading (maxDepth: 1) |
+| `useNetworkAware` | `hooks/` | Network condition detection |
+| `useReversePlayback` | `hooks/` | Video reverse playback |
+| `useOfflineMode` | `hooks/` | Offline download management |
+| `useStorageQuota` | `hooks/` | Storage quota monitoring |
+
+### TypeScript Types
+
+```
+types/
+├── api.ts          # PaginatedResponse, FetchParams, ApiError
+├── entities.ts     # BaseEntity, User, Role, Project, Asset, etc.
+├── redux.ts        # Entity slice configuration
+├── constructor.ts  # Tour builder specific types
+├── runtime.ts      # Runtime environment types
+├── offline.ts      # PWA and offline types
+├── preload.ts      # Preloading system types
+├── permissions.ts  # Permission enum definitions
+├── presentation.ts # Presentation runtime types
+├── filters.ts      # Filter system types
+├── forms.ts        # Form field types
+└── index.ts        # Central exports
+```
+
+### Frontend Configuration
+
+```typescript
+// config/config.ts
+const config = {
+  apiBaseUrl: process.env.NEXT_PUBLIC_BACK_API || 'http://localhost:3000/api',
+  appTitle: 'Shimahara Visual',
+  storageKeys: {
+    darkMode: 'tour-builder-dark-mode',
+    stylePrefs: 'tour-builder-style',
+  },
+};
+```
+
+### Build Configuration
+
+```javascript
+// next.config.mjs
+{
+  // PWA with Serwist
+  swSrc: 'src/sw.ts',
+  swDest: 'public/sw.js',
+  disable: process.env.NODE_ENV === 'development',
+
+  // Next.js settings
+  trailingSlash: true,
+  distDir: process.env.NODE_ENV === 'development' ? '.next' : 'build',
+  output: process.env.NEXT_OUTPUT || undefined,
+  images: { unoptimized: true },
+
+  // Development
+  experimental: { turbo: true }
+}
+```
+
+---
+
+## Backend Architecture
+
+### Directory Structure
+
+```
+backend/src/
+├── routes/             # Express route handlers (22 routes)
+├── db/
+│   ├── models/         # Sequelize model definitions (16 models)
+│   ├── api/            # Database access layer (GenericDBApi)
+│   ├── migrations/     # Database schema migrations
+│   ├── seeders/        # Seed data scripts
+│   ├── db-config.ts    # Database configuration
+│   └── umzug.ts        # Migration and seeder runner
+├── services/           # Business logic services
+├── auth/               # Passport.js strategies
+├── middlewares/        # Express middlewares
+├── factories/          # Factory patterns
+└── utils/              # Logger, error handling
+```
+
+### Three-Tier Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Routes Layer                              │
+│  Express handlers │ Request validation │ Response formatting    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                       Services Layer                             │
+│  Business logic │ Transactions │ External integrations          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                        DB API Layer                              │
+│  Sequelize queries │ Filtering │ Associations │ Transformations │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Factory Patterns
+
+**Router Factory** (`factories/router.factory.js`):
+
+```javascript
+// Generates standard CRUD routes automatically
+module.exports = createEntityRouter('assets', AssetsService, AssetsDBApi, {
+  permissionEntity: 'assets',
+  csvFields: ['name', 'url', 'type'],
+  customRoutes: (router) => {
+    router.get('/custom', customHandler);
+  }
+});
+
+// Generated routes:
+// GET    /api/assets          - List with pagination/filtering
+// GET    /api/assets/:id      - Get single entity
+// POST   /api/assets          - Create entity
+// PUT    /api/assets/:id      - Update entity
+// DELETE /api/assets/:id      - Delete entity
+// POST   /api/assets/bulk-import   - CSV import
+// DELETE /api/assets/deleteByIds   - Bulk delete
+```
+
+**Service Factory** (`factories/service.factory.js`):
+
+```javascript
+// Creates service class with transaction handling
+module.exports = createEntityService('assets', AssetsDBApi);
+
+// Generated methods:
+// create({ data, currentUser, transaction, runtimeContext }) - Create with transaction
+// update({ id, data, currentUser, transaction, runtimeContext }) - Update with transaction
+// remove({ id, currentUser, transaction, runtimeContext }) - Delete with transaction
+// bulkImport(data, options) - Batch import
+// deleteByIds({ ids, currentUser, transaction, runtimeContext }) - Batch delete
+```
+
+**GenericDBApi** (`db/api/base.api.js`):
+
+```javascript
+class GenericDBApi {
+  // Override in entity APIs
+  MODEL = null;
+  SEARCHABLE_FIELDS = [];      // Text search fields
+  RANGE_FIELDS = [];           // Numeric/date range filters
+  ENUM_FIELDS = [];            // Exact match filters
+  ASSOCIATIONS = [];           // Related entity loading
+
+  // Transform input before save
+  getFieldMapping(data) { return data; }
+
+  // Standard operations
+  findAll(query, options) { }
+  findOne(id, options) { }
+  create(data, options) { }
+  update({ id, data, currentUser, transaction, runtimeContext }) { }
+  remove({ id, currentUser, transaction, runtimeContext }) { }
+}
+```
+
+### Middleware Stack
+
+```javascript
+// Applied in order
+app.use(helmet());                    // Security headers
+app.use(cors({ origin: true }));      // CORS
+app.use(requestLogger);               // Request logging
+app.use(runtimeContext);              // Admin/stage/production detection
+app.use(bodyParser.json());           // JSON parsing
+app.use(passport.initialize());       // Auth initialization
+
+// Per-route middleware
+router.use(passport.authenticate('jwt'));  // JWT validation
+router.use(checkPermissions);              // RBAC check
+```
+
+### Authentication System
+
+**Passport Strategies:**
+
+```javascript
+// 1. JWT Strategy (primary)
+passport.use(new JwtStrategy({
+  jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+  secretOrKey: process.env.SECRET_KEY,
+}, async (payload, done) => {
+  const user = await findUserByEmail(payload.email);
+  if (user && !user.disabled) {
+    return done(null, user);
+  }
+  return done(null, false);
+}));
+
+// 2. Google OAuth 2.0
+passport.use(new GoogleStrategy({
+  clientID: process.env.GOOGLE_CLIENT_ID,
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+  callbackURL: '/api/auth/signin/google/callback',
+}, findOrCreateUser));
+
+// 3. Microsoft OAuth
+passport.use(new MicrosoftStrategy({...}, findOrCreateUser));
+```
+
+**JWT Configuration:**
+- Secret: `process.env.SECRET_KEY`
+- Expiration: 6 hours
+- Payload: `{ id, email, name }`
+
+### Runtime Context System
+
+The platform uses **route-based environment access** (not subdomains):
+
+| Route | Environment | Purpose |
+|-------|-------------|---------|
+| `/p/[slug]` | production | Public presentation |
+| `/p/[slug]/stage` | stage | Preview presentation |
+| `/constructor?projectId=` | dev | Editor (always dev) |
+
+**Middleware** (`middleware/runtime-context.ts`):
+
+```javascript
+// Detects context from hostname AND headers
+req.runtimeContext = {
+  mode: detectFromHostname(hostname),     // 'admin' | 'stage' | 'production'
+  projectSlug: fromHostname || null,
+  headerEnvironment: req.headers['x-runtime-environment'],  // Route-based
+  headerProjectSlug: req.headers['x-runtime-project-slug'], // Route-based
+};
+```
+
+**Environment Resolution** (`db/api/runtime-context.ts`):
+
+```javascript
+// Priority: hostname-based → header-based
+// SECURITY: Only 'production' and 'stage' allowed from headers
+// 'dev' from header is ignored to prevent unauthorized access
+```
+
+**Frontend Filtering** (`RuntimePresentation.tsx`):
+
+```javascript
+// STRICT: Only exact environment match
+.filter((p) => p.environment === environment)
+```
+
+See [Publishing Workflow](./publishing-workflow.md) for complete environment isolation details.
+
+### Permissions System
+
+```javascript
+// middlewares/check-permissions.ts
+const checkPermissions = async (req, res, next) => {
+  // 1. Self-access bypass
+  if (req.params.id === req.currentUser.id) {
+    return next();
+  }
+
+  // 2. Check custom permissions
+  const customPermission = await findCustomPermission(
+    req.currentUser.id,
+    req.permissionEntity,
+    req.method
+  );
+  if (customPermission) return next();
+
+  // 3. Check role-based permissions
+  const rolePermission = await findRolePermission(
+    req.currentUser.app_role,
+    req.permissionEntity,
+    req.method
+  );
+  if (rolePermission) return next();
+
+  return res.status(403).json({ error: 'Forbidden' });
+};
+```
+
+### File Storage System
+
+```javascript
+// Configurable via FILE_STORAGE_PROVIDER env var
+const providers = {
+  s3: new S3StorageProvider({
+    bucket: process.env.AWS_S3_BUCKET,
+    region: process.env.AWS_S3_REGION,
+  }),
+  gcloud: new GCloudStorageProvider({...}),
+  local: new LocalStorageProvider({
+    basePath: './uploads',
+  }),
+};
+
+// File service with chunked upload support
+class FileService {
+  async initUpload(filename, totalChunks) { }
+  async uploadChunk(sessionId, chunkIndex, data) { }
+  async finalizeUpload(sessionId) { }
+  async getDownloadUrl(fileKey) { }
+}
+```
+
+**S3 Presigned URLs for Direct Download:**
+
+The platform supports direct asset downloads from S3 for better performance:
+
+```javascript
+// POST /api/file/presign - Get presigned URLs for batch download
+// Request: { urls: ["assets/image1.jpg", "assets/video.mp4", ...] }
+// Response: { presignedUrls: { "assets/image1.jpg": "https://s3...", ... } }
+// - Max 50 URLs per request
+// - 1-hour expiry
+// - Public endpoint (no auth required for runtime)
+```
+
+Frontend preloading uses presigned URLs:
+1. Request presigned URLs via `POST /api/file/presign`
+2. Download directly from S3 (bypasses backend)
+3. Store in Cache API (dual key: download URL + storage key)
+4. Create blob URL for instant playback
+5. Store in `readyBlobUrlsRef` (dual key: download URL + storage key) for O(1) lookup
+
+**Storage Key Mapping:** Assets are cached under both download URL and canonical storage key (e.g., `assets/project/video.mp4`). This ensures cache hits even when presigned URL signatures change.
+
+---
+
+## Database Schema
+
+### Core Domain Models
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Element Defaults Hierarchy                    │
+│                                                                  │
+│  ┌─────────────────────┐                                        │
+│  │ element_type_defaults│ ─── Global platform-wide defaults     │
+│  └──────────┬──────────┘                                        │
+│             │ (auto-snapshot on project creation)               │
+│             ▼                                                   │
+│  ┌─────────────────────┐                                        │
+│  │project_element_defaults│ ─── Project-specific overrides      │
+│  └──────────┬──────────┘                                        │
+│             │ (applies defaults to new elements)                │
+│             ▼                                                   │
+│  ┌─────────────────────┐                                        │
+│  │   Page Elements     │ ─── Instance-specific on pages         │
+│  └─────────────────────┘                                        │
+└─────────────────────────────────────────────────────────────────┘
+
+┌─────────────────┐     ┌─────────────────┐
+│    Projects     │────<│   Tour Pages    │
+└─────────────────┘     └─────────────────┘
+        │                       │
+        │                       ▼
+        │               ┌─────────────────────────────────────┐
+        │               │       ui_schema_json (inline)       │
+        │               │  • Page Elements                    │
+        │               │  • Navigation Links (targetPageSlug)│
+        │               │  • Transition Videos                │
+        │               └─────────────────────────────────────┘
+        ▼
+┌─────────────────┐
+│     Assets      │
+└─────────────────┘
+        │
+        ▼
+┌─────────────────┐
+│ Asset Variants  │
+└─────────────────┘
+
+Note: Page elements, navigation links, and transition configurations
+are stored inline in tour_pages.ui_schema_json (not separate tables).
+Navigation uses targetPageSlug for cross-environment consistency.
+```
+
+### Entity Relationships
+
+| Entity | Relationships |
+|--------|--------------|
+| **Projects** | hasMany: tour_pages, assets, project_audio_tracks, publish_events, project_element_defaults, project_memberships, presigned_url_requests, pwa_caches, access_logs |
+| **Tour Pages** | belongsTo: project; contains ui_schema_json with elements, navigation (targetPageSlug), and transitions (transitionVideoUrl) |
+| **Assets** | belongsTo: project; hasMany: asset_variants |
+| **Users** | belongsTo: role; hasMany: custom_permissions |
+| **Element Type Defaults** | hasMany: project_element_defaults (as source_element) |
+| **Project Element Defaults** | belongsTo: project, element_type_defaults (as source_element) |
+
+**Note:** Page elements, navigation links, and transitions are stored inline in `tour_pages.ui_schema_json` rather than as separate tables. Navigation uses `targetPageSlug` (not UUIDs) for cross-environment consistency during publishing.
+
+### Common Fields Pattern
+
+All entities include:
+
+```javascript
+{
+  id: UUID,                 // Primary key
+  createdAt: TIMESTAMP,     // Creation timestamp
+  updatedAt: TIMESTAMP,     // Last update timestamp
+  deletedAt: TIMESTAMP,     // Soft delete (paranoid)
+  createdBy: UUID,          // User who created
+  updatedBy: UUID,          // User who last updated
+}
+```
+
+### Key Models
+
+**Projects:**
+```javascript
+{
+  id, name, slug, description,
+  logo_url, favicon_url, og_image_url,
+}
+```
+
+**Tour Pages:**
+```javascript
+{
+  id, name, slug, sort_order,
+  projectId, environment,
+  background_image_url,
+  background_video_url,
+  background_audio_url,
+  background_loop,
+  requires_auth,
+  ui_schema_json,            // Page layout/elements
+}
+```
+
+**Page Elements:**
+```javascript
+{
+  id, element_type, name, sort_order,  // element_type is TEXT (not ENUM)
+  pageId,
+  is_visible,
+  x_percent, y_percent,      // Position as percentage (0-100)
+  width_percent, height_percent,
+  rotation_deg,
+  content_json,              // Element-specific data
+  style_json,                // CSS properties
+}
+```
+
+**Element Type Defaults (Global):**
+```javascript
+{
+  id, element_type, name, sort_order,  // Unique element_type per platform
+  default_settings_json,      // JSON-serialized default settings
+  // 11 predefined types: navigation_next, navigation_prev, spot, tooltip,
+  // description, gallery, carousel, logo, video_player, audio_player, popup
+}
+```
+
+**Project Element Defaults:**
+```javascript
+{
+  id, element_type, name, sort_order,
+  projectId,
+  settings_json,              // Project-specific settings override
+  source_element_id,          // FK to element_type_defaults (for tracking)
+  snapshot_version,           // Version for "check for updates" feature
+  // Auto-snapshotted from global defaults on project creation
+}
+```
+
+**Assets:**
+```javascript
+{
+  id, name, projectId,
+  asset_type,                // 'image' | 'video' | 'audio' | 'file'
+  type,                      // 'general' | 'icon' | 'background_image' | 'audio' | 'video' | 'transition' | 'logo' | 'favicon' | 'document'
+  cdn_url, storage_key, mime_type,
+  size_mb, width_px, height_px, duration_sec,
+  checksum, is_public,
+}
+```
+
+**Navigation Elements (stored in ui_schema_json):**
+```javascript
+// Navigation elements with transitions are stored inline in tour_pages.ui_schema_json
+{
+  id, element_type,  // 'navigation_next', 'navigation_prev', 'spot', etc.
+  targetPageSlug,    // Target page for navigation (not UUID)
+  transitionVideoUrl,          // Forward transition video
+  transitionDurationSec,       // Duration in seconds
+  transitionReverseMode,       // 'auto_reverse' | 'separate_video' (replaces supportsReverse)
+  reverseVideoUrl,             // Separate reverse video (when mode is 'separate_video')
+  // ...other element properties
+}
+```
+
+**Note:** There is no separate `transitions` table. Transition data is stored directly on navigation elements within each page's `ui_schema_json`.
+
+---
+
+## Data Flow
+
+### Authentication Flow
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   Login Page    │────>│  POST /signin   │────>│  Validate Creds │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+                                                        │
+                                                        ▼
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Store Token    │<────│  Return JWT     │<────│  Generate JWT   │
+│  (sessionStorage)│     │                 │     │  (6h expiry)    │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Axios Interceptor attaches token to all subsequent requests    │
+│  Authorization: Bearer <token>                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### CRUD Operation Flow
+
+```
+┌─────────────────┐
+│ Redux dispatch  │
+│ fetch({query})  │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│   Axios GET     │────>│  JWT Middleware │
+│  /api/entity    │     │  (validate)     │
+└─────────────────┘     └────────┬────────┘
+                                 │
+                                 ▼
+┌─────────────────┐     ┌─────────────────┐
+│  Permissions    │<────│  Route Handler  │
+│  Middleware     │     │                 │
+└────────┬────────┘     └─────────────────┘
+         │
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│    Service      │────>│    DB API       │
+│  (transactions) │     │  (Sequelize)    │
+└─────────────────┘     └────────┬────────┘
+                                 │
+                                 ▼
+┌─────────────────┐     ┌─────────────────┐
+│   PostgreSQL    │────>│  JSON Response  │
+│    Query        │     │  {rows, count}  │
+└─────────────────┘     └────────┬────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────┐
+│  Redux slice updates state              │
+│  Components re-render with new data     │
+└─────────────────────────────────────────┘
+```
+
+### Asset Upload Flow
+
+```
+┌─────────────────┐     ┌─────────────────┐
+│ useAssetUploader│────>│  Split into     │
+│  hook           │     │  chunks (5MB)   │
+└─────────────────┘     └────────┬────────┘
+                                 │
+                                 ▼
+┌─────────────────┐     ┌─────────────────┐
+│  POST /init     │────>│  Create upload  │
+│  (get sessionId)│     │  session        │
+└─────────────────┘     └────────┬────────┘
+                                 │
+                                 ▼
+┌─────────────────┐     ┌─────────────────┐
+│  POST /chunk    │────>│  Store chunk    │
+│  (each chunk)   │     │  (S3/local)     │
+└─────────────────┘     └────────┬────────┘
+                                 │ (repeat)
+                                 ▼
+┌─────────────────┐     ┌─────────────────┐
+│ POST /finalize  │────>│  Combine chunks │
+│                 │     │  Create Asset   │
+└─────────────────┘     └────────┬────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────┐
+│  Return asset metadata with CDN URL     │
+└─────────────────────────────────────────┘
+```
+
+### Asset Preloading Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1. Page Load - Initialize preloading                            │
+│     └── usePreloadOrchestrator initializes                       │
+│     └── extractPageLinksAndElements(pages) extracts assets       │
+│     └── useNeighborGraph builds navigation graph (maxDepth: 1)   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  2. Batch presigned URL request                                  │
+│     └── POST /api/file/presign { urls: [...] }                   │
+│     └── Returns S3 presigned URLs (1-hour expiry, max 50)        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  3. Priority queue downloads (3 concurrent)                      │
+│     └── Transition: +150 │ Image: +100 │ Audio: +50 │ Video: +30│
+│     └── Current page: 1000 base │ Neighbor: 500 base            │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  4. Download directly from S3                                    │
+│     └── fetch(presignedUrl)                                      │
+│     └── Store in Cache API (<5MB) or IndexedDB (≥5MB)           │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  5. Create ready blob URL (dual key storage)                     │
+│     └── URL.createObjectURL(blob)                                │
+│     └── Decode image (if applicable)                             │
+│     └── Store in readyBlobUrlsRef Map:                          │
+│         • key: downloadUrl → blobUrl                             │
+│         • key: storageKey → blobUrl (canonical, never changes)  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  6. Navigation - Instant asset display                           │
+│     └── usePageSwitch.switchToPage(targetPage)                   │
+│     └── getReadyBlobUrl(storageKey) → O(1) instant lookup        │
+│     └── Smooth page transition without black flash               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## API Patterns
+
+### Standard Endpoints
+
+Every entity follows this pattern:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/{entity}` | List with pagination |
+| GET | `/api/{entity}/:id` | Get single entity |
+| POST | `/api/{entity}` | Create entity |
+| PUT | `/api/{entity}/:id` | Update entity |
+| DELETE | `/api/{entity}/:id` | Delete entity |
+| POST | `/api/{entity}/bulk-import` | CSV import |
+| DELETE | `/api/{entity}/deleteByIds` | Bulk delete |
+
+### Query Parameters
+
+```
+# Pagination
+?limit=100&page=1&offset=0
+
+# Sorting
+?sortField=createdAt&sortOrder=DESC
+
+# Text search (SEARCHABLE_FIELDS)
+?search=keyword
+
+# Range filters (RANGE_FIELDS)
+?createdAtRange=2024-01-01,2024-12-31
+?sizeRange=0,1000000
+
+# Enum filters (ENUM_FIELDS)
+?type=image&status=active
+
+# Export
+?filetype=csv
+```
+
+### Response Format
+
+```javascript
+// List response
+{
+  rows: [...],           // Array of entities
+  count: 100,            // Total count (for pagination)
+}
+
+// Single entity
+{
+  id: "uuid",
+  ...entityFields,
+  createdAt: "2024-01-01T00:00:00Z",
+  updatedAt: "2024-01-01T00:00:00Z",
+}
+
+// Error response
+{
+  error: "Error message",
+  details: {...},        // Optional
+}
+```
+
+---
+
+## Environment Configuration
+
+### Backend (.env)
+
+```bash
+# Database
+DB_NAME=app_39215
+DB_USER=app_39215
+DB_PASS=password
+DB_HOST=localhost
+DB_PORT=5432
+
+# Authentication
+SECRET_KEY=jwt-secret-key
+GOOGLE_CLIENT_ID=...
+GOOGLE_CLIENT_SECRET=...
+MS_CLIENT_ID=...
+MS_CLIENT_SECRET=...
+
+# File Storage (S3)
+FILE_STORAGE_PROVIDER=s3
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+AWS_S3_BUCKET=tour-builder-assets
+AWS_S3_REGION=us-east-1
+AWS_S3_PREFIX=uploads/
+
+# Email (AWS SES)
+EMAIL_USER=...
+EMAIL_PASS=...
+
+PEXELS_KEY=...
+
+# Runtime
+# Optional. If omitted by backend scripts, src/load-env.ts defaults to dev_stage.
+NODE_ENV=dev_stage
+```
+
+### Frontend (.env.local)
+
+```bash
+NEXT_PUBLIC_BACK_API=http://localhost:3000/api
+```
+
+### Database Configuration
+
+Database configuration lives in `backend/src/db/db-config.ts`. Database
+commands are executed by the typed Umzug runner in `backend/src/db/umzug.ts`.
+`backend/src/load-env.ts` loads `backend/.env` for app and DB entrypoints; if
+`NODE_ENV` is absent it defaults to `dev_stage`, matching the standard VM
+backend process.
+
+---
+
+## Key Files Reference
+
+### Frontend
+
+| File | Purpose |
+|------|---------|
+| `pages/_app.tsx` | App wrapper, providers, axios interceptor |
+| `stores/store.ts` | Redux store configuration |
+| `stores/createEntitySlice.ts` | Entity slice factory |
+| `config/config.ts` | App configuration |
+| `config/preload.config.ts` | Preload priorities and settings |
+| `next.config.mjs` | Next.js + Serwist config |
+| `src/sw.ts` | Service worker |
+| `hooks/usePreloadOrchestrator.ts` | Asset preloading with S3 presigned URLs |
+| `hooks/usePageSwitch.ts` | Page navigation with preloaded blob URLs |
+| `lib/extractPageLinks.ts` | Extract navigation links from ui_schema_json |
+| `lib/offline/StorageManager.ts` | Cache API and IndexedDB storage |
+| `components/RuntimePresentation.tsx` | Runtime with environment filtering |
+
+### Backend
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Express app setup, middleware stack |
+| `factories/router.factory.ts` | CRUD route generator |
+| `factories/service.factory.ts` | Service class generator |
+| `db/api/base.api.ts` | GenericDBApi base class |
+| `db/api/element_type_defaults.ts` | Global element defaults with auto-seed |
+| `db/api/project_element_defaults.ts` | Project element defaults with snapshot |
+| `services/publish.ts` | Dev → Stage → Production publishing |
+| `auth/auth.ts` | Passport strategies |
+| `middlewares/check-permissions.ts` | RBAC middleware |
+
+---
+
+## Common Commands
+
+### Backend
+
+```bash
+cd backend
+
+# Install dependencies
+npm install
+
+# Start server (port 3000 in dev_stage)
+npm run start-dev
+
+# Database operations
+npm run db:create    # Create database
+npm run db:migrate   # Run migrations
+npm run db:seed      # Seed data
+npm run db:drop      # Drop database
+
+# Linting
+npm run lint
+```
+
+### Frontend
+
+```bash
+cd frontend
+
+# Install dependencies
+npm install
+
+# Development server (port 3001)
+npm run dev
+
+# Production build
+npm run build
+
+# Linting and formatting
+npm run lint
+npm run format
+```
+
+### Docker
+
+```bash
+cd docker
+
+# First time setup
+chmod +x start-backend.sh wait-for-it.sh
+
+# Start all services
+docker-compose up
+
+# Fresh database
+rm -rf data && docker-compose up
+```
+
+---
+
+## Security Considerations
+
+1. **JWT Authentication** - 6-hour expiration, secure secret key
+2. **RBAC** - Role-based access control with custom overrides
+3. **Helmet** - Security headers (XSS, CSRF protection)
+4. **CORS** - Configured for specific origins
+5. **SQL Injection** - Prevented via Sequelize parameterized queries
+6. **Soft Delete** - Paranoid mode preserves audit trail
+7. **File Validation** - MIME type and size checks on upload
+
+---
+
+## Performance Optimizations
+
+1. **Chunked Uploads** - Prevents memory overload for large files
+2. **Pagination** - All list endpoints support limit/offset
+3. **Lazy Loading** - Redux thunks load data on demand
+4. **Asset Variants** - Multiple quality levels (thumbnail, preview, etc.)
+5. **PWA Caching** - Service worker caches static assets
+6. **S3 Direct Download** - Assets downloaded directly from S3 via presigned URLs (bypasses backend)
+7. **Ready Blob URLs** - Pre-created blob URLs stored in memory for O(1) instant lookup (`getReadyBlobUrl`)
+8. **Storage Key Mapping** - Assets cached by canonical storage key (e.g., `assets/vid.mp4`) enabling cache hits regardless of presigned URL signature changes
+9. **Neighbor Preloading** - BFS traversal preloads immediate neighbors (maxDepth: 1)
+10. **Priority Queue** - Transitions (+150), images (+100), audio (+50), video (+30)
+11. **IndexedDB** - Large files (≥5MB) stored locally for offline access
+12. **Cache API** - Small files (<5MB) stored in browser Cache API
+13. **Blob URL Rendering** - Native `<img>` tags for blob URLs to prevent Next.js Image re-fetch on re-renders
diff --git a/documentation/project-improvement-todo.ru.md b/documentation/project-improvement-todo.ru.md
new file mode 100644
index 0000000..9adc26b
--- /dev/null
+++ b/documentation/project-improvement-todo.ru.md
@@ -0,0 +1,182 @@
+# TODO по улучшению проекта
+
+Дата исследования: 2026-06-28
+
+Цель: строгий, но не enterprise-heavy backlog для небольшого production-проекта. Система должна стать более предсказуемой: явные boundaries, единые contracts, единая модель доступа, единый подход к server state и API validation. Улучшения выполняются маленькими PR без большого rewrite.
+
+## Принципы
+
+- Сначала фиксируем текущее поведение тестами/чеклистами, потом рефакторим.
+- Для нового кода целевые правила обязательны; старый код приводится к ним постепенно.
+- Не добавляем тяжёлую инфраструктуру "на будущее", но добавляем строгие boundaries там, где уже есть production-risk.
+- Для risky changes используем маленькие PR и manual verification.
+- Документацию в `documentation/` обновляем только когда реально меняется API, schema, workflow или deployment.
+
+## Целевые правила архитектуры
+
+Backend:
+
+- Route/controller layer: только auth/context, validation, вызов service, response mapping.
+- Service/domain layer: business logic, permissions decisions, transactions.
+- DB API/repository layer: только data access, filters, includes, pagination.
+- Policy layer: вся логика доступа в одном месте, не в отдельных routes.
+- Validation layer: все внешние body/query/params проходят schema validation.
+
+Frontend:
+
+- Redux: только client/app state.
+- TanStack Query: server state, lists/details/mutations/cache invalidation.
+- Feature code: новая feature-specific логика живёт рядом с feature, а не размазывается по generic folders.
+- `any`, type assertions/casts, disabled hook rules и direct axios calls в feature components не являются целевым стандартом.
+
+## P1 - Frontend
+
+### Разделить самые большие файлы по строгим boundaries
+
+Boundaries должны быть строгими.
+
+TODO:
+
+- `constructor.tsx`: выносить pure helpers, feature hooks и state reducers в отдельные файлы.
+- `RuntimePresentation.tsx`: выносить navigation/media/preload helpers и state logic в отдельные files/hooks.
+- Feature-specific файлы класть рядом с feature, а не в generic `components`.
+
+### Redux и TanStack Query
+
+Redux не нужно удалять полностью.
+
+Оставить Redux для:
+
+- auth/session UI;
+- theme/style;
+- layout/sidebar;
+- constructor UI state;
+- app preferences.
+
+Целевое правило: server data не хранится в Redux. Existing entity Redux slices считаются legacy и заменяются на TanStack Query по одному flow.
+
+TODO:
+
+- Зафиксировать правило: Redux для client/app state, TanStack Query для server state.
+- Не создавать новые entity CRUD Redux slices.
+- Пилотно мигрировать один простой entity flow (`roles` или `permissions`) на TanStack Query.
+- Не удалять старый Redux slice, пока все consumers entity не мигрированы.
+- API reads/mutations делать через TanStack Query hooks, не через Redux thunks.
+
+### Frontend TypeScript strictness
+
+Цель: включить strict TypeScript как обязательный стандарт для frontend и закрыть legacy errors без сохранения JS/CommonJS как допустимого направления. Новый и изменённый код должен быть strict-compatible.
+
+TODO:
+
+- Посчитать текущий frontend typecheck baseline: сколько ошибок даёт `strict: true`.
+- Включать strictness по шагам: сначала отдельный strict config для selected folders/new code, затем общий `strict: true`, когда baseline закрыт.
+- Для новых/изменённых файлов запрещать новый `any` без явной причины.
+- Запретить новые type assertions/casts (`as`, angle-bracket assertions, non-null `!`) в feature code. Исключения: validated external boundaries, DOM/library interop, discriminated unions после guard; исключение должно быть локальным и объяснённым.
+- Вернуть `no-unused-vars`/unused imports как warning, затем поднять до error после cleanup.
+- Добавить frontend `typecheck` script и включить его в minimal checks, когда baseline проходит.
+- `react-hooks/exhaustive-deps` включать file-by-file после исправления конкретных hooks.
+
+### Auth storage
+
+Сейчас token пишется и в `sessionStorage`, и в `localStorage`.
+
+TODO:
+
+- Решить, нужен ли persistent login.
+- Если persistent login не нужен, оставить только `sessionStorage`.
+- Если нужен, оставить `localStorage`, но осознанно и с коротким TTL/refresh policy.
+- Заменить frontend `jsonwebtoken` decode на `jwt-decode` или `/auth/me`.
+
+### Минимальные regression checks
+
+Начать с smoke tests/checklist:
+
+- login;
+- constructor load/save;
+- save to stage;
+- publish;
+- public production runtime;
+- private production runtime grant;
+- page navigation;
+- rest.
+
+## P1 - Build и зависимости
+
+### Package manager
+
+Сейчас есть смешение lockfiles/scripts.
+
+TODO:
+
+- Выбрать один package manager для frontend/backend.
+- Удалить лишний lockfile после проверки install/build.
+- Обновить docs/deployment commands.
+
+### Dependencies LTS alignment и obsolete package replacement
+
+Зависимости нужно обновлять осознанно, чтобы не закреплять старые toolchain limitations и устаревшие библиотеки.
+
+TODO:
+
+- Проверить текущие frontend/backend dependencies и devDependencies на совместимость с выбранным Node LTS.
+- Обновить TypeScript, ESLint, `@typescript-eslint/*`, Next.js/React tooling и backend runtime tooling до актуальных LTS/stable versions.
+- Найти deprecated, unsupported и obsolete packages через package manager audit/outdated/deprecation warnings, npm metadata, release notes и project documentation.
+- Для deprecated/unsupported/obsolete packages выбрать actively maintained mainstream alternatives с широкой adoption, свежими releases, нормальной TypeScript/ESM support и понятным migration path.
+- Для каждой замены зафиксировать причину: что именно deprecated/unsupported/obsolete, какой replacement выбран, какие breaking changes ожидаются.
+- Проверить DB scripts, migrations/seeders, test runner и production start после dependency updates.
+- Не делать blind major upgrades без changelog/release notes и rollback plan.
+
+### Node version
+
+TODO:
+
+- Зафиксировать выбранный Node LTS через `backend/package.json` `engines.node`.
+- Согласовать `engines.node`.
+- Обновить `@types/node` во frontend, когда будет удобно.
+
+### CI/minimal checks
+
+Для небольшого проекта достаточно минимального gate:
+
+- frontend build;
+- frontend lint/typecheck, если проходит;
+- backend lint;
+- smoke checklist перед deploy.
+
+Audit/outdated/license checks делать периодически, не обязательно blocking на каждый PR.
+
+## P2 - Security hardening
+
+### CSP
+
+Полный CSP может быть сложным из-за embeds/media. Не вводить сразу.
+
+TODO:
+
+- Сначала собрать список нужных domains для assets/embeds.
+- Если будет время, включить report-only CSP на stage.
+- Enforced CSP делать только после проверки runtime presentations.
+
+## P2 - Документация
+
+TODO:
+
+- Обновить docs только для реально изменённых workflows/API/schema.
+
+## Рекомендуемый порядок
+
+1. Добавить validation для самых рискованных endpoints и запретить новые routes без validation.
+2. Проверить DB slow queries и добавить только реально нужные индексы.
+3. Выбрать package manager и Node version.
+4. Добавить минимальные smoke checks.
+5. Постепенно выносить helpers из больших frontend/backend файлов при изменениях.
+6. Пилотно перевести один entity flow с Redux на TanStack Query.
+7. Делать cleanup/dependency upgrades небольшими отдельными PR.
+
+## Definition of Done
+
+- Production workflows проверены вручную или тестом.
+- Нет большого rewrite без явной выгоды.
+- DB changes имеют backup/rollback plan.
+- Документация обновлена только там, где изменилось поведение.
diff --git a/documentation/project-memberships.md b/documentation/project-memberships.md
new file mode 100644
index 0000000..81ce74f
--- /dev/null
+++ b/documentation/project-memberships.md
@@ -0,0 +1,429 @@
+# Project Memberships
+
+Complete documentation for the Tour Builder Platform's Project Memberships system including team collaboration, member roles, and access control per project.
+
+## Overview
+
+The Project Memberships system enables team collaboration by managing user access to specific projects. It operates as a separate access layer from the application-level RBAC system, allowing granular per-project permissions.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                     Project Memberships Architecture                         │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │              Application-Level RBAC (roles table)                       │ │
+│  │      Controls which users can manage project memberships                │ │
+│  │                                                                         │ │
+│  │   • PlatformOwner, Administrator: Full CRUD on memberships             │ │
+│  │   • AccountManager: Create, Read, Update (no delete)                   │ │
+│  │   • TourDesigner, ContentReviewer, AnalyticsViewer: Read only          │ │
+│  └─────────────────────────────┬──────────────────────────────────────────┘ │
+│                                │                                             │
+│                   (permission to manage)                                     │
+│                                │                                             │
+│                                ▼                                             │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │              Project-Level Access (project_memberships)                 │ │
+│  │      Controls what users can do within a specific project              │ │
+│  │                                                                         │ │
+│  │   Project A                      Project B                              │ │
+│  │   ┌─────────────────────┐       ┌─────────────────────┐                │ │
+│  │   │ User1: owner        │       │ User2: owner        │                │ │
+│  │   │ User2: editor       │       │ User3: viewer       │                │ │
+│  │   │ User3: reviewer     │       │ User4: editor       │                │ │
+│  │   └─────────────────────┘       └─────────────────────┘                │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Data Model
+
+### Database Schema
+
+**Table:** `project_memberships`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key (auto-generated) |
+| `access_level` | ENUM | Project role: `owner`, `editor`, `reviewer`, `viewer` |
+| `is_active` | BOOLEAN | Whether membership is active (default: false) |
+| `invited_at` | DATE | When invitation was sent |
+| `accepted_at` | DATE | When user accepted invitation |
+| `projectId` | UUID | Foreign key to `projects` table |
+| `userId` | UUID | Foreign key to `users` table |
+| `createdAt` | TIMESTAMP | Record creation time |
+| `updatedAt` | TIMESTAMP | Record update time |
+| `deletedAt` | TIMESTAMP | Soft delete timestamp (paranoid mode) |
+| `importHash` | STRING(255) | Unique hash for CSV imports |
+
+**Source:** `backend/src/db/models/project_memberships.js`
+
+### Database Indexes
+
+```javascript
+indexes: [
+  { fields: ['projectId'] },              // Fast project lookups
+  { fields: ['userId'] },                 // Fast user lookups
+  { fields: ['projectId', 'userId'], unique: true },  // One membership per user-project
+  { fields: ['is_active'] },              // Filter by active status
+  { fields: ['deletedAt'] },              // Soft delete queries
+]
+```
+
+### Relationships
+
+```javascript
+// Each membership belongs to one project
+db.project_memberships.belongsTo(db.projects, {
+  as: 'project',
+  foreignKey: 'projectId',
+  onDelete: 'CASCADE',  // Delete membership when project is deleted
+  onUpdate: 'CASCADE',
+});
+
+// Each membership belongs to one user
+db.project_memberships.belongsTo(db.users, {
+  as: 'user',
+  foreignKey: 'userId',
+  onDelete: 'CASCADE',  // Delete membership when user is deleted
+  onUpdate: 'CASCADE',
+});
+
+// Audit trail associations
+db.project_memberships.belongsTo(db.users, { as: 'createdBy' });
+db.project_memberships.belongsTo(db.users, { as: 'updatedBy' });
+```
+
+## Project Access Levels
+
+### ENUM Values
+
+| Level | Description | Typical Permissions |
+|-------|-------------|---------------------|
+| `owner` | Full project control | All operations, can delete project, manage team |
+| `editor` | Content editing | Edit pages, elements, assets, transitions |
+| `reviewer` | Review only | View all content, add comments/feedback |
+| `viewer` | Read-only | View published content only |
+
+**Default:** `viewer` (when not specified)
+
+### Access Level Hierarchy
+
+```
+owner → editor → reviewer → viewer
+  │        │         │         │
+  │        │         │         └── View published content
+  │        │         └── View all content + provide feedback
+  │        └── Edit content + reviewer permissions
+  └── Full control + editor permissions + manage team
+```
+
+## Invitation Workflow
+
+### Membership States
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     Invitation Lifecycle                             │
+│                                                                      │
+│  1. Membership Created                                               │
+│     ├── invited_at: timestamp                                        │
+│     ├── accepted_at: null                                            │
+│     └── is_active: false                                             │
+│                                                                      │
+│                    ↓                                                 │
+│                                                                      │
+│  2. User Accepts Invitation                                          │
+│     ├── invited_at: original timestamp                               │
+│     ├── accepted_at: timestamp                                       │
+│     └── is_active: true                                              │
+│                                                                      │
+│                    ↓                                                 │
+│                                                                      │
+│  3. Membership Active                                                │
+│     └── User can access project with assigned access_level          │
+│                                                                      │
+│                    ↓ (optional)                                      │
+│                                                                      │
+│  4. Membership Revoked (soft delete)                                 │
+│     └── deletedAt: timestamp (paranoid mode)                        │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Timestamp Fields
+
+| Field | Set When | Purpose |
+|-------|----------|---------|
+| `invited_at` | Membership created | Track when invitation was sent |
+| `accepted_at` | User accepts | Track when user joined project |
+| `is_active` | User accepts | Quick filter for active members |
+
+## API Reference
+
+### Endpoint
+
+**Base URL:** `/api/project_memberships`
+
+**Source:** `backend/src/routes/project_memberships.ts`
+
+### Standard Operations
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/project_memberships` | List all memberships |
+| `GET` | `/api/project_memberships/:id` | Get single membership |
+| `POST` | `/api/project_memberships` | Create membership (invite user) |
+| `PUT` | `/api/project_memberships/:id` | Update membership |
+| `DELETE` | `/api/project_memberships/:id` | Delete membership (soft delete) |
+
+### Request/Response Format
+
+**Create Membership:**
+```json
+POST /api/project_memberships
+{
+  "data": {
+    "project": "project-uuid",
+    "user": "user-uuid",
+    "access_level": "editor",
+    "invited_at": "2024-01-15T10:00:00Z"
+  }
+}
+```
+
+**Query with Filters:**
+```
+GET /api/project_memberships?project=<uuid>&access_level=editor&is_active=true
+```
+
+### Filtering Options
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `project` | UUID/name | Filter by project ID or name (iLike search) |
+| `user` | UUID/firstName | Filter by user ID or firstName (iLike search) |
+| `access_level` | ENUM | Filter by access level |
+| `is_active` | boolean | Filter by active status |
+| `invited_atRange` | [start, end] | Filter by invitation date range |
+| `accepted_atRange` | [start, end] | Filter by acceptance date range |
+| `createdAtRange` | [start, end] | Filter by record creation date range |
+
+**Source:** `backend/src/db/api/project_memberships.ts`
+
+## Application-Level Permissions
+
+### Permission Names
+
+The RBAC system uses these permissions to control who can manage memberships:
+
+| Permission | Description |
+|------------|-------------|
+| `CREATE_PROJECT_MEMBERSHIPS` | Invite users to projects |
+| `READ_PROJECT_MEMBERSHIPS` | View project team members |
+| `UPDATE_PROJECT_MEMBERSHIPS` | Change user access levels |
+| `DELETE_PROJECT_MEMBERSHIPS` | Remove users from projects |
+
+### Role-Permission Matrix
+
+| Role | CREATE | READ | UPDATE | DELETE |
+|------|--------|------|--------|--------|
+| PlatformOwner | ✓ | ✓ | ✓ | ✓ |
+| Administrator | ✓ | ✓ | ✓ | ✓ |
+| AccountManager | ✓ | ✓ | ✓ | ✗ |
+| TourDesigner | ✗ | ✓ | ✗ | ✗ |
+| ContentReviewer | ✗ | ✓ | ✗ | ✗ |
+| AnalyticsViewer | ✗ | ✓ | ✗ | ✗ |
+
+**Source:** `backend/src/db/seeders/20200430130760-user-roles.js`
+
+## Frontend Integration
+
+### Redux State Management
+
+**Slice:** `frontend/src/stores/project_memberships/project_membershipsSlice.ts`
+
+```typescript
+import { createEntitySlice } from '../createEntitySlice';
+import type { ProjectMembership } from '../../types/entities';
+
+const { slice, actions, reducer } = createEntitySlice<ProjectMembership>({
+  name: 'project_memberships',
+  endpoint: 'project_memberships',
+  singularName: 'Project Membership',
+});
+
+export const {
+  fetch,
+  create,
+  update,
+  deleteItem,
+  deleteItemsByIds,
+  uploadCsv,
+  setRefetch,
+} = actions;
+```
+
+### TypeScript Interface
+
+**Source:** `frontend/src/types/entities.ts`
+
+```typescript
+export interface ProjectMembership extends BaseEntity {
+  user?: User | string | null;
+  project?: Project | string | null;
+  access_level?: 'owner' | 'editor' | 'reviewer' | 'viewer';
+  is_active?: boolean;
+  invited_at?: string | Date | null;
+  accepted_at?: string | Date | null;
+  // Legacy field
+  role?: 'owner' | 'editor' | 'viewer';
+}
+```
+
+### Admin Pages
+
+**Location:** `frontend/src/pages/project_memberships/`
+
+| Page | Path | Description |
+|------|------|-------------|
+| List | `/project_memberships/project_memberships-list` | Paginated table with filters (factory-generated) |
+| Table | `/project_memberships/project_memberships-table` | Alternative table view (manual implementation) |
+| New | `/project_memberships/project_memberships-new` | Create membership form |
+| Edit (query) | `/project_memberships/project_memberships-edit?id=<uuid>` | Edit membership form (query param) |
+| Edit (path) | `/project_memberships/<uuid>` | Edit membership form (path param) |
+| View | `/project_memberships/project_memberships-view?id=<uuid>` | Read-only details |
+
+**Note:** Two edit routes exist - query-based (`?id=`) and dynamic path-based (`[project_membershipsId].tsx`).
+
+**Table Columns:** project, user, access_level, is_active, invited_at, accepted_at, actions
+
+**List Filters:** access_level (enum dropdown with owner/editor/reviewer/viewer options), project (text search), user (text search), invited_at (date range), accepted_at (date range)
+
+> **Note:** `is_active` filter is supported by the API but not exposed in the admin list UI.
+
+**Components:** `frontend/src/components/Project_memberships/`
+- `TableProject_memberships.tsx` - Data grid component (23 LOC)
+- `CardProject_memberships.tsx` - Card view component (163 LOC)
+- `ListProject_memberships.tsx` - List view component (125 LOC)
+- `configureProject_membershipsCols.tsx` - Column definitions with permission-based editability (51 LOC)
+
+### Usage Example
+
+```typescript
+import { useAppDispatch, useAppSelector } from '../stores/hooks';
+import { fetch, create, update, deleteItem } from '../stores/project_memberships/project_membershipsSlice';
+
+// Fetch project members
+dispatch(fetch({ query: `?project=${projectId}&is_active=true` }));
+
+// Invite user to project
+dispatch(create({
+  project: projectId,
+  user: userId,
+  access_level: 'editor',
+  invited_at: new Date().toISOString(),
+}));
+
+// Update access level
+dispatch(update({
+  id: membershipId,
+  access_level: 'reviewer',
+}));
+
+// Remove from project
+dispatch(deleteItem(membershipId));
+```
+
+## Unique Constraint
+
+The composite unique index on `(projectId, userId)` ensures:
+- Each user can only have one membership per project
+- Attempting to invite the same user twice will fail
+- To change a user's role, update the existing membership
+
+```sql
+-- This constraint prevents duplicate memberships
+CREATE UNIQUE INDEX ON project_memberships (projectId, userId);
+```
+
+## Soft Delete Behavior
+
+The model uses Sequelize's paranoid mode:
+- `DELETE` operations set `deletedAt` timestamp instead of removing record
+- Default queries exclude soft-deleted records
+- Membership history is preserved for audit purposes
+
+```javascript
+{
+  timestamps: true,
+  paranoid: true,  // Enables soft delete
+}
+```
+
+## Known Considerations
+
+1. **Two-Tier Access System**: Application-level roles control who can manage memberships; project-level access controls what users can do within projects.
+
+2. **Invitation Flow**: Memberships start with `is_active: false`. The system tracks `invited_at` and `accepted_at` separately to support invitation workflows.
+
+3. **Legacy Field**: The TypeScript interface includes a `role` field for backward compatibility, but the database uses `access_level` ENUM.
+
+4. **Cascade Deletes**: Memberships are automatically deleted when their associated project or user is deleted.
+
+5. **Dedicated Admin Pages**: Standard CRUD pages exist at `/project_memberships/*`:
+   - `project_memberships-list.tsx` - List with filters using factory pattern (35 LOC)
+   - `project_memberships-table.tsx` - Alternative table view (185 LOC, manual implementation)
+   - `project_memberships-new.tsx` - Create new membership (149 LOC)
+   - `project_memberships-edit.tsx` - Edit via query param (200 LOC)
+   - `[project_membershipsId].tsx` - Edit via path param (221 LOC)
+   - `project_memberships-view.tsx` - View membership details (163 LOC)
+   - Components: `TableProject_memberships`, `CardProject_memberships`, `ListProject_memberships`
+
+6. **Default Access Level**: New memberships default to `viewer` access, the most restrictive level.
+
+7. **Autocomplete Field**: The DB API uses `access_level` for autocomplete searches, enabling dropdown-style user interfaces.
+
+## Data Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       Team Collaboration Flow                                │
+│                                                                              │
+│  Project Owner                    Backend API                     Database  │
+│       │                               │                               │     │
+│       │ POST /project_memberships     │                               │     │
+│       │ {user, project, editor}       │                               │     │
+│       │──────────────────────────────>│                               │     │
+│       │                               │                               │     │
+│       │                               │ Check CREATE_PROJECT_         │     │
+│       │                               │ MEMBERSHIPS permission        │     │
+│       │                               │                               │     │
+│       │                               │ Validate unique constraint    │     │
+│       │                               │──────────────────────────────>│     │
+│       │                               │                               │     │
+│       │                               │ Create membership record      │     │
+│       │                               │ invited_at: now               │     │
+│       │                               │ is_active: false              │     │
+│       │                               │<──────────────────────────────│     │
+│       │                               │                               │     │
+│       │<──────────────────────────────│                               │     │
+│       │ 200 OK {membership}           │                               │     │
+│                                                                              │
+│  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  │
+│                                                                              │
+│  Invited User                                                               │
+│       │ PUT /project_memberships/:id                                        │
+│       │ {is_active: true}             │                               │     │
+│       │──────────────────────────────>│                               │     │
+│       │                               │                               │     │
+│       │                               │ Update membership             │     │
+│       │                               │ accepted_at: now              │     │
+│       │                               │ is_active: true               │     │
+│       │                               │──────────────────────────────>│     │
+│       │                               │<──────────────────────────────│     │
+│       │<──────────────────────────────│                               │     │
+│       │                               │                               │     │
+│       │ User can now access project   │                               │     │
+│       │ with 'editor' permissions     │                               │     │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
diff --git a/documentation/project-transition-settings.md b/documentation/project-transition-settings.md
new file mode 100644
index 0000000..0cb88b4
--- /dev/null
+++ b/documentation/project-transition-settings.md
@@ -0,0 +1,585 @@
+# Project Transition Settings
+
+Documentation for the environment-aware project-level transition settings system that cascades with global and element-level settings.
+
+## Overview
+
+Project transition settings control the default CSS-based transition behavior for page navigation when no video transition is configured on an element. Settings are stored per-project and per-environment, following the same publishing pattern as `tour_pages` and `project_audio_tracks`.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Transition Settings Cascade                           │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────────┐│
+│  │  Element Level (highest priority)                                   ││
+│  │  └── ui_schema_json.elements[].transitionSettings                  ││
+│  └─────────────────────────────────────────────────────────────────────┘│
+│                              ↓ fallback                                  │
+│  ┌─────────────────────────────────────────────────────────────────────┐│
+│  │  Project Level (per environment)                                    ││
+│  │  └── project_transition_settings WHERE projectId AND environment   ││
+│  └─────────────────────────────────────────────────────────────────────┘│
+│                              ↓ fallback                                  │
+│  ┌─────────────────────────────────────────────────────────────────────┐│
+│  │  Global Level (platform-wide defaults)                              ││
+│  │  └── global_transition_defaults (single record)                    ││
+│  └─────────────────────────────────────────────────────────────────────┘│
+│                              ↓ fallback                                  │
+│  ┌─────────────────────────────────────────────────────────────────────┐│
+│  │  Hardcoded Fallback                                                 ││
+│  │  └── type: 'fade', durationMs: 700, easing: 'ease-in-out'         ││
+│  └─────────────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Environment-Aware Architecture
+
+Project transition settings follow the same environment isolation pattern as tour pages:
+
+```
+Publishing Flow:
+┌─────────────────────────────────────────────────────────────────┐
+│  Constructor (dev)                                              │
+│  └── project_transition_settings WHERE environment='dev'        │
+│                           ↓                                     │
+│                    [Save to Stage]                              │
+│                           ↓                                     │
+│  Stage (Preview)                                                │
+│  └── project_transition_settings WHERE environment='stage'      │
+│                           ↓                                     │
+│                     [Publish]                                   │
+│                           ↓                                     │
+│  Production (Public)                                            │
+│  └── project_transition_settings WHERE environment='production' │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Database Schema
+
+### Table: `project_transition_settings`
+
+| Column | Type | Nullable | Default | Description |
+|--------|------|----------|---------|-------------|
+| id | UUID | No | UUIDV4 | Primary key |
+| projectId | UUID | No | - | FK to projects (CASCADE delete) |
+| environment | ENUM | No | - | 'dev', 'stage', 'production' |
+| source_key | TEXT | Yes | null | Tracks source record during publishing |
+| transition_type | TEXT | No | 'fade' | CSS transition type ('fade', 'none') |
+| duration_ms | INTEGER | No | 700 | Transition duration in milliseconds |
+| easing | TEXT | No | 'ease-in-out' | CSS easing function |
+| overlay_color | TEXT | No | '#000000' | Color of transition overlay |
+| createdById | UUID | Yes | - | FK to users |
+| updatedById | UUID | Yes | - | FK to users |
+| createdAt | TIMESTAMP | No | NOW() | Creation timestamp |
+| updatedAt | TIMESTAMP | No | NOW() | Last update timestamp |
+| deletedAt | TIMESTAMP | Yes | null | Soft delete timestamp |
+
+**Indexes:**
+- `project_transition_settings_project_env_unique` - UNIQUE on (projectId, environment) WHERE deletedAt IS NULL
+
+**Constraints:**
+- Only one active record per project/environment combination
+- Soft delete (paranoid: true)
+
+## API Endpoints
+
+### Authentication Model
+
+The API uses **URL-path-based public access** for runtime presentations:
+
+| Endpoint | Method | Environment | Auth Required |
+|----------|--------|-------------|---------------|
+| `/project/:id/env/production` | GET | production | **No** (public) |
+| `/project/:id/env/dev` | GET | dev | Yes |
+| `/project/:id/env/stage` | GET | stage | Yes |
+| `/project/:id/env/*` | PUT/DELETE | any | Yes |
+| Standard CRUD (`/`, `/:id`) | all | n/a | Yes |
+
+This allows public presentations (`/p/[slug]`) to fetch production transition settings without authentication, while protecting dev/stage environments and write operations.
+
+Write operations use the `PAGE_ELEMENTS` permission family because transition
+defaults are authored as part of the tour page/element editing surface. Global
+defaults and project environment upserts require `UPDATE_PAGE_ELEMENTS`.
+Environment-level reset uses `DELETE` to remove the project override row, but
+authorization treats it as an update and also requires `UPDATE_PAGE_ELEMENTS`
+rather than `DELETE_PAGE_ELEMENTS`.
+
+### Get Settings by Project and Environment
+
+```http
+GET /api/project-transition-settings/project/:projectId/env/:environment
+# Production: No auth required (public)
+# Dev/Stage: Authorization: Bearer {token}
+```
+
+**Response (200):**
+```json
+{
+  "id": "uuid",
+  "projectId": "project-uuid",
+  "environment": "dev",
+  "transition_type": "fade",
+  "duration_ms": 700,
+  "easing": "ease-in-out",
+  "overlay_color": "#000000",
+  "createdAt": "2026-05-01T12:00:00Z",
+  "updatedAt": "2026-05-01T12:00:00Z"
+}
+```
+
+**Response (200) when no settings exist:** `null` (use global defaults)
+
+**Response (401):** Authentication required (for dev/stage without JWT)
+
+### Create or Update Settings
+
+```http
+PUT /api/project-transition-settings/project/:projectId/env/:environment
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "transition_type": "fade",
+  "duration_ms": 1000,
+  "easing": "ease-out",
+  "overlay_color": "#1a1a1a"
+}
+```
+
+**Response (200):** Created or updated settings object
+
+### Delete Settings
+
+```http
+DELETE /api/project-transition-settings/project/:projectId/env/:environment
+Authorization: Bearer {token}
+```
+
+**Response (200):** `{ "success": true }`
+
+### Standard CRUD Endpoints (All Require Auth)
+
+```
+GET    /api/project-transition-settings           - List all
+GET    /api/project-transition-settings/:id       - Get by ID
+POST   /api/project-transition-settings           - Create
+PUT    /api/project-transition-settings/:id       - Update
+DELETE /api/project-transition-settings/:id       - Delete
+```
+
+## Publishing Integration
+
+### Copy During Save to Stage / Publish
+
+Project transition settings are copied along with tour pages and audio tracks:
+
+```javascript
+// In PublishService.copyEnvironment()
+const [sourcePages, sourceAudioTracks, sourceTransitionSettings] = await Promise.all([
+  db.tour_pages.findAll({ where: { projectId, environment: fromEnv }, transaction }),
+  db.project_audio_tracks.findAll({ where: { projectId, environment: fromEnv }, transaction }),
+  db.project_transition_settings.findOne({ where: { projectId, environment: fromEnv }, transaction }),
+]);
+
+// Clean up target environment
+await Promise.all([
+  db.tour_pages.destroy({ where: { projectId, environment: toEnv }, transaction, force: true }),
+  db.project_audio_tracks.destroy({ where: { projectId, environment: toEnv }, transaction, force: true }),
+  db.project_transition_settings.destroy({ where: { projectId, environment: toEnv }, transaction, force: true }),
+]);
+
+// Copy transition settings if exists
+if (sourceTransitionSettings) {
+  await db.project_transition_settings.create({
+    ...sanitizedData,
+    projectId,
+    environment: toEnv,
+    source_key: sourceTransitionSettings.id,
+    createdById: actorId,
+    updatedById: actorId,
+  }, { transaction });
+}
+```
+
+### Source Key Tracking
+
+The `source_key` field tracks the lineage of copied records:
+- When copying dev → stage: stage record's `source_key` = dev record's `id`
+- When copying stage → production: production record's `source_key` = stage record's `id`
+
+## Frontend Integration
+
+### Redux Store
+
+**File:** `frontend/src/stores/project_transition_settings/projectTransitionSettingsSlice.ts`
+
+```typescript
+interface ProjectTransitionSettingsState {
+  byProjectEnv: Record<string, ProjectTransitionSettingsEntity | null>;
+  loading: boolean;
+  loadingKeys: Record<string, boolean>;
+}
+
+// Actions - no special headers needed, backend determines public access from URL path
+fetchByProjectAndEnv({ projectId, environment })
+upsertByProjectAndEnv({ projectId, environment, data })
+deleteByProjectAndEnv({ projectId, environment })
+
+// Selectors
+selectByProjectAndEnv(state, projectId, environment)
+selectTransitionSettingsLoading(state, projectId, environment)
+```
+
+**Global Transition Defaults Store**
+
+**File:** `frontend/src/stores/global_transition_defaults/globalTransitionDefaultsSlice.ts`
+
+```typescript
+// Simple fetch - backend GET is always public
+export const fetch = createAsyncThunk<GlobalTransitionDefaults, void>(
+  'global_transition_defaults/fetch',
+  async () => {
+    const result = await axios.get('global-transition-defaults');
+    return result.data;
+  }
+);
+```
+
+### Type Definitions
+
+**File:** `frontend/src/types/transition.ts`
+
+```typescript
+// Database entity (snake_case)
+interface ProjectTransitionSettingsEntity extends BaseEntity {
+  projectId: string;
+  environment: 'dev' | 'stage' | 'production';
+  source_key?: string;
+  transition_type: TransitionType;
+  duration_ms: number;
+  easing: EasingFunction;
+  overlay_color: string;
+}
+
+// Cascade resolution format (camelCase)
+interface ProjectTransitionSettings {
+  transitionType?: TransitionType;
+  durationMs?: number;
+  easing?: EasingFunction;
+  overlayColor?: string;
+}
+
+// Convert entity to cascade format
+function entityToProjectSettings(entity): ProjectTransitionSettings | null
+```
+
+### Hook: useTransitionSettings
+
+**File:** `frontend/src/hooks/useTransitionSettings.ts`
+
+Resolves final transition settings through the cascade:
+
+```typescript
+const transitionSettings = useTransitionSettings({
+  globalDefaults,      // From global_transition_defaults table
+  projectSettings,     // From project_transition_settings (converted via entityToProjectSettings)
+  elementSettings,     // From element's ui_schema_json
+});
+
+// Returns: ResolvedTransitionSettings
+// { type, durationMs, easing, overlayColor, videoUrl?, reverseVideoUrl? }
+```
+
+### Constructor Usage
+
+**File:** `frontend/src/pages/constructor.tsx`
+
+```typescript
+// Fetch dev environment settings
+useEffect(() => {
+  if (projectId) {
+    dispatch(fetchProjectTransitionSettings({ projectId, environment: 'dev' }));
+  }
+}, [dispatch, projectId]);
+
+// Select from store
+const projectTransitionSettingsEntity = useAppSelector((state) =>
+  projectId ? selectProjectTransitionSettings(state, projectId, 'dev') : undefined
+);
+
+// Convert for cascade resolution
+const projectTransitionSettings = useMemo(
+  () => entityToProjectSettings(projectTransitionSettingsEntity),
+  [projectTransitionSettingsEntity]
+);
+```
+
+### Runtime Presentation Usage
+
+**File:** `frontend/src/components/RuntimePresentation.tsx`
+
+```typescript
+// Fetch environment-specific settings
+useEffect(() => {
+  if (project?.id) {
+    dispatch(fetchProjectTransitionSettings({ projectId: project.id, environment }));
+  }
+}, [dispatch, project?.id, environment]);
+
+// Use in transition settings resolution
+const transitionSettings = useTransitionSettings({
+  globalDefaults,
+  projectSettings,  // Environment-specific
+  elementSettings: currentElementTransitionSettings,  // From React state
+});
+```
+
+### Element Settings State Tracking
+
+Both `constructor.tsx` and `RuntimePresentation.tsx` track element-level transition settings via React state:
+
+```typescript
+// State for current element's transition settings
+const [currentElementTransitionSettings, setCurrentElementTransitionSettings] =
+  useState<ElementTransitionSettings | null>(null);
+```
+
+**Extracting settings from clicked elements:**
+
+```typescript
+import { extractElementTransitionSettings } from '../types/transition';
+
+// In click handler, extract settings from the navigation element
+const elementSettings = extractElementTransitionSettings(clickedElement);
+```
+
+The `extractElementTransitionSettings()` function converts element fields to `ElementTransitionSettings` format:
+- Only includes fields with actual values (not empty strings)
+- Allows cascade to fall through when element uses "Use Project Default"
+- Handles type coercion for `transitionType` and `transitionEasing`
+
+### Critical: React Timing Fix with flushSync
+
+**Problem:** React's async state batching can cause transitions to start with OLD settings values.
+
+When a user clicks a navigation button, this sequence happens:
+1. `setCurrentElementTransitionSettings(elementSettings)` is called
+2. `switchToPage()` starts the transition
+3. `useTransitionSettings` hook resolves final settings
+
+Without synchronization, step 2 can execute before React processes step 1, causing the transition to use stale settings.
+
+**Solution:** Use `flushSync` from `react-dom` to force synchronous state updates:
+
+```typescript
+import { flushSync } from 'react-dom';
+
+// In handleElementClick:
+const elementSettings = extractElementTransitionSettings(clickedElement);
+
+// Force synchronous state update BEFORE navigation starts
+flushSync(() => {
+  setCurrentElementTransitionSettings(elementSettings);
+});
+
+// Now transition will use the correct settings
+switchToPage(targetPageId, transitionConfig);
+```
+
+**Files affected:**
+- `frontend/src/pages/constructor.tsx`
+- `frontend/src/components/RuntimePresentation.tsx`
+
+### TourFlowManager (Settings UI)
+
+**File:** `frontend/src/components/TourFlowManager.tsx`
+
+The TourFlowManager component provides a UI for editing project transition settings in the dev environment:
+
+```typescript
+// Fetch and display current settings
+const projectTransitionSettingsEntity = useAppSelector((state) =>
+  selectedProjectId ? selectByProjectAndEnv(state, selectedProjectId, 'dev') : undefined
+);
+
+// Save changes
+const handleSaveTransitionSettings = async () => {
+  await dispatch(upsertByProjectAndEnv({
+    projectId: selectedProjectId,
+    environment: 'dev',
+    data: {
+      transition_type: localTransitionType,
+      duration_ms: localDurationMs,
+      easing: localEasing,
+      overlay_color: localOverlayColor,
+    },
+  }));
+};
+```
+
+## Transition Types
+
+| Type | CSS Behavior | Description |
+|------|--------------|-------------|
+| `fade` | opacity 0→1 | Smooth crossfade between pages |
+| `none` | No animation | Instant page switch |
+
+## Easing Functions
+
+| Value | CSS equivalent | Description |
+|-------|----------------|-------------|
+| `linear` | linear | Constant speed |
+| `ease` | ease | Standard easing |
+| `ease-in` | ease-in | Slow start |
+| `ease-out` | ease-out | Slow end |
+| `ease-in-out` | ease-in-out | Slow start and end |
+
+## Video Transition Priority
+
+When an element has a `transitionVideoUrl`, the video transition **always takes precedence** over CSS-based transitions:
+
+```typescript
+if (elementSettings?.transitionVideoUrl) {
+  return {
+    type: 'video',
+    durationMs: elementSettings.transitionDurationMs ?? FALLBACK_DEFAULTS.durationMs,
+    easing: elementSettings.transitionEasing ?? FALLBACK_DEFAULTS.easing,
+    overlayColor: /* cascade through element → project → global */,
+    videoUrl: elementSettings.transitionVideoUrl,
+    reverseVideoUrl: elementSettings.reverseVideoUrl,
+  };
+}
+```
+
+## File References
+
+| File | Purpose |
+|------|---------|
+| `backend/src/db/migrations/20260501000002-create-project-transition-settings.js` | Database migration |
+| `backend/src/db/models/project_transition_settings.js` | Sequelize model |
+| `backend/src/db/api/project_transition_settings.ts` | Database API layer |
+| `backend/src/services/project_transition_settings.ts` | Service layer |
+| `backend/src/routes/project_transition_settings.ts` | REST endpoints |
+| `backend/src/services/publish.ts` | Publishing integration |
+| `frontend/src/stores/project_transition_settings/projectTransitionSettingsSlice.ts` | Redux store |
+| `frontend/src/types/transition.ts` | TypeScript definitions |
+| `frontend/src/hooks/useTransitionSettings.ts` | Cascade resolution hook |
+| `frontend/src/components/TourFlowManager.tsx` | Settings UI |
+| `frontend/src/pages/constructor.tsx` | Constructor integration |
+| `frontend/src/components/RuntimePresentation.tsx` | Runtime integration |
+
+## Troubleshooting
+
+### Settings Not Applying
+
+1. Verify settings exist: `GET /api/project-transition-settings/project/:id/env/:environment`
+2. Check cascade order - element settings override project settings
+3. Ensure correct environment is being queried (dev/stage/production)
+
+### Settings Not Publishing
+
+1. Check publish event completed successfully
+2. Verify source environment has settings before publish
+3. Check `source_key` in target environment record
+
+### Missing Settings After Project Creation
+
+New projects don't automatically get project-level settings. They use:
+1. Global defaults (if configured)
+2. Hardcoded fallback (fade, 700ms, ease-in-out)
+
+To set project defaults, use TourFlowManager or API.
+
+---
+
+## Slide Transitions (Gallery/Carousel)
+
+Slide transitions for Gallery and Carousel elements cascade from page transition settings, with optional element-level overrides.
+
+### Cascade Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Slide Transition Cascade                              │
+│                                                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │  Element Override (highest priority)                              │  │
+│  │  └── gallerySlideTransition* / carouselSlideTransition* fields   │  │
+│  └────────────────────────────┬─────────────────────────────────────┘  │
+│                               ↓ fallback                                │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │  Page Transition Settings (resolved via useTransitionSettings)    │  │
+│  │  └── Global → Project cascade (see above)                        │  │
+│  └────────────────────────────┬─────────────────────────────────────┘  │
+│                               ↓ fallback                                │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │  Hardcoded Fallback                                               │  │
+│  │  └── type: 'fade', durationMs: 700, easing: 'ease-in-out',       │  │
+│  │      overlayColor: '#000000'                                      │  │
+│  └──────────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Element Override Fields
+
+Stored in `tour_pages.ui_schema_json.elements[]`:
+
+**Carousel:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `carouselSlideTransitionType` | `'fade' \| 'none' \| ''` | Transition type ('' = use default) |
+| `carouselSlideTransitionDurationMs` | `number \| ''` | Duration in ms |
+| `carouselSlideTransitionEasing` | `EasingFunction \| ''` | CSS easing |
+| `carouselSlideTransitionOverlayColor` | `string` | Overlay color (hex) |
+
+**Gallery:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `gallerySlideTransitionType` | `'fade' \| 'none' \| ''` | Transition type ('' = use default) |
+| `gallerySlideTransitionDurationMs` | `number \| ''` | Duration in ms |
+| `gallerySlideTransitionEasing` | `EasingFunction \| ''` | CSS easing |
+| `gallerySlideTransitionOverlayColor` | `string` | Overlay color (hex) |
+
+### Slide vs Page Transition Differences
+
+| Aspect | Page Transitions | Slide Transitions |
+|--------|------------------|-------------------|
+| Video type | Supported | Maps to 'fade' (no video between slides) |
+| Overlay color | Yes (fade through overlay) | Yes (same behavior) |
+| Duration | Configurable | Inherits from page or element override |
+| Element override | Navigation element | Gallery/Carousel element |
+
+### Implementation Files
+
+| File | Purpose |
+|------|---------|
+| `frontend/src/lib/resolveSlideTransition.ts` | Cascade resolver + extractors |
+| `frontend/src/hooks/useSlideTransition.ts` | Animation state management hook |
+| `frontend/src/components/UiElements/elements/CarouselElement.tsx` | Carousel with crossfade |
+| `frontend/src/components/UiElements/GalleryCarouselOverlay.tsx` | Gallery/Info Panel fullscreen media overlay with crossfade |
+| `frontend/src/components/ElementSettings/EffectsSettingsSectionCompact.tsx` | Element editor UI |
+
+### Animation Mechanism
+
+The `useSlideTransition` hook implements fade-through-overlay animation:
+
+```
+Phase 1: Fade Out (half duration)
+├── overlayOpacity: 0 → 1
+└── slideOpacity: 1 → 0
+
+Phase 2: Swap (at midpoint)
+└── displayIndex switches to new slide
+
+Phase 3: Fade In (half duration)
+├── overlayOpacity: 1 → 0
+└── slideOpacity: 0 → 1
+```
+
+### Backwards Compatibility
+
+Existing elements without slide transition fields automatically cascade to page transition settings or hardcoded fallbacks. No database migration required - fields are stored in JSON column.
+
+**Behavior for existing projects:**
+- Elements with page transitions configured → inherits those settings
+- Elements with no page transitions → uses hardcoded fallback (fade, 700ms)
diff --git a/documentation/publishing-workflow.md b/documentation/publishing-workflow.md
new file mode 100644
index 0000000..bbfa4ca
--- /dev/null
+++ b/documentation/publishing-workflow.md
@@ -0,0 +1,996 @@
+# Publishing Workflow
+
+Complete documentation for the Tour Builder Platform's publishing system including the three-tier environment model (dev → stage → production), publish events, and transaction locking.
+
+## Overview
+
+The platform implements a **three-tier environment publishing system**:
+- **Dev** - Active editing environment (constructor always edits here)
+- **Stage** - Preview/testing environment for stakeholder review
+- **Production** - Live environment for public access
+
+The publishing workflow has two steps:
+1. **Save to Stage**: Copy dev content to stage for preview
+2. **Publish to Production**: Copy stage content to production
+
+Projects maintain environment-specific data (pages, audio tracks) that can be independently edited and published. The system uses database transactions with project-level locks to prevent concurrent publishing conflicts. Page elements and transitions are stored directly in `tour_pages.ui_schema_json`.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Three-Tier Publishing Flow                            │
+│                                                                          │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                 │
+│  │     Dev     │    │    Stage    │    │ Production  │                 │
+│  │ Environment │───▶│ Environment │───▶│ Environment │                 │
+│  └─────────────┘    └─────────────┘    └─────────────┘                 │
+│        │                  │                   │                         │
+│        │ Edit in          │ Preview           │ Public Access           │
+│        │ Constructor      │                   │                         │
+│        ▼                  ▼                   ▼                         │
+│   /constructor       /p/[slug]/stage      /p/[slug]                    │
+│                                                                          │
+│  [Save to Stage]──────────▶                                             │
+│                    [Publish to Production]──────────▶                    │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      Database Structure                                  │
+│                                                                          │
+│  Projects ─────────┬─────────────────┬─────────────────┐                │
+│     │              │                 │                 │                │
+│     ▼              ▼                 ▼                 ▼                │
+│  tour_pages    audio_tracks   transition_settings  publish_events      │
+│  (env field)   (env field)    (env field)          (history)           │
+│                                                                          │
+│  environment: 'dev' | 'stage' | 'production'                           │
+│                                                                          │
+│  Note: Elements, links, and transitions are stored in                  │
+│        tour_pages.ui_schema_json (no separate tables)                  │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Stage vs Production Environments
+
+### Environment-Specific Entities
+
+Each of these entities maintains an `environment` field:
+
+| Entity | Environment Field | Description |
+|--------|------------------|-------------|
+| `tour_pages` | Yes | Pages with backgrounds, content, and `ui_schema_json` |
+| `project_audio_tracks` | Yes | Project audio files |
+| `project_transition_settings` | Yes | CSS transition settings (type, duration, easing, overlay color) |
+
+**Note:** Page elements, navigation links, and video transitions are stored directly in `tour_pages.ui_schema_json` and are copied with the page when publishing. Project-level CSS transition settings are stored separately in `project_transition_settings` and also copied during publish.
+
+### URL Patterns
+
+**Stage Environment:**
+```
+/p/[projectSlug]/stage
+```
+- Route: `frontend/src/pages/p/[projectSlug]/stage.tsx`
+- Loads pages with `environment='stage'` only
+
+**Production Environment:**
+```
+/p/[projectSlug]
+```
+- Route: `frontend/src/pages/p/[projectSlug]/index.tsx`
+- Loads pages with `environment='production'` only
+
+## Environment Isolation (Security)
+
+**CRITICAL:** Strict environment filtering prevents data leaks between environments.
+
+### Defense in Depth
+
+The system uses **two layers** of environment protection:
+
+| Layer | File | Protection |
+|-------|------|------------|
+| **Frontend** | `RuntimePresentation.tsx` | Strict filter: `p.environment === environment` |
+| **Backend** | `db/api/runtime-context.ts` | Filters by `X-Runtime-Environment` header |
+
+### Frontend Filtering
+
+Environment filtering happens in the `usePageDataLoader` hook, which is used by `RuntimePresentation.tsx`:
+
+```typescript
+// hooks/usePageDataLoader.ts - STRICT environment match only
+// For runtime mode, filter by environment client-side
+if (projectSlug) {
+  pageRows = pageRows.filter((p) => p.environment === environment);
+}
+
+// Sort by sort_order
+pageRows.sort((a, b) => (a.sort_order ?? 0) - (b.sort_order ?? 0));
+```
+
+- Production mode (`/p/cardiff`): Only shows `environment='production'` pages
+- Stage mode (`/p/cardiff/stage`): Only shows `environment='stage'` pages
+- Dev mode (Constructor): Only shows `environment='dev'` pages
+- **No fallbacks** - missing environment data shows empty, never leaks from other environments
+
+### Backend Filtering
+
+The backend also filters based on the `X-Runtime-Environment` header:
+
+```javascript
+// db/api/runtime-context.ts
+// Only 'production' and 'stage' allowed from header
+// 'dev' is BLOCKED to prevent unauthorized access
+if (runtimeContext.headerEnvironment === 'production') return 'production';
+if (runtimeContext.headerEnvironment === 'stage') return 'stage';
+// 'dev' header returns null → no backend filter (constructor handles separately)
+```
+
+### Database Constraints
+
+Environment columns are enforced at the database level:
+
+```sql
+-- tour_pages.environment: NOT NULL, default 'dev'
+-- project_audio_tracks.environment: NOT NULL, default 'dev'
+-- project_transition_settings.environment: NOT NULL
+```
+
+This prevents NULL values from bypassing environment filters.
+
+**Constructor (Dev Environment):**
+```
+/constructor?projectId=[id]
+```
+- Route: `frontend/src/pages/constructor.tsx`
+- Always loads and edits pages with `environment='dev'`
+- "Save to Stage" button copies dev → stage
+
+### Runtime Mode Detection
+
+**Primary Method: Route-Based Access**
+
+The platform uses **route-based environment access**, not subdomains:
+
+| Route | Environment | Component |
+|-------|-------------|-----------|
+| `/p/[slug]` | production | `pages/p/[projectSlug]/index.tsx` |
+| `/p/[slug]/stage` | stage | `pages/p/[projectSlug]/stage.tsx` |
+| `/constructor?projectId=` | dev | `pages/constructor.tsx` |
+
+**Frontend Headers for API Calls:**
+```javascript
+// RuntimePresentation sends these headers
+headers: {
+  'X-Runtime-Project-Slug': projectSlug,
+  'X-Runtime-Environment': environment  // 'production' | 'stage' | 'dev'
+}
+```
+
+**Backend Middleware** (`backend/src/middlewares/runtime-context.ts`):
+
+The middleware reads environment and project slug from headers for route-based access:
+
+```javascript
+// req.runtimeContext structure
+{
+  mode: 'admin',                     // default mode
+  projectSlug: null,                 // not used in current implementation
+  headerEnvironment: string | null,  // from X-Runtime-Environment header ('production', 'stage', 'dev')
+  headerProjectSlug: string | null,  // from X-Runtime-Project-Slug header
+}
+```
+
+**Environment Resolution** (`backend/src/db/api/runtime-context.ts`):
+
+The `getRuntimeEnvironment()` function resolves environment in order:
+1. Hostname-based detection (stage/production subdomains)
+2. Header-based fallback (`X-Runtime-Environment` header)
+
+```javascript
+// Only 'production' and 'stage' are allowed from headers
+// 'dev' is blocked to prevent unauthorized access to dev data
+if (runtimeContext.headerEnvironment === 'production') return 'production';
+if (runtimeContext.headerEnvironment === 'stage') return 'stage';
+```
+
+### Project Slug
+
+The `slug` field on projects determines public URLs:
+
+| Property | Value |
+|----------|-------|
+| Pattern | `/^[a-z0-9_-]+$/i` |
+| Length | 1-255 characters |
+| Uniqueness | Must be unique across all projects |
+| Mutability | Should not change (breaks public URLs) |
+
+**Example:**
+```
+slug: 'cardiff'
+Stage URL: /p/cardiff/stage
+Production URL: /p/cardiff
+```
+
+## Publish Events
+
+### Database Schema
+
+**File:** `backend/src/db/models/publish_events.js`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | UUID | Yes | Primary key |
+| title | STRING(255) | No* | User-provided event name (*DB allows null, service validates, max 255 chars) |
+| description | TEXT | No* | User-provided details (*DB allows null, service validates, max 5000 chars) |
+| from_environment | ENUM | Yes | Source: 'dev', 'stage', 'production' |
+| to_environment | ENUM | Yes | Target: 'dev', 'stage', 'production' |
+| status | ENUM | Yes | 'queued', 'running', 'success', 'failed' |
+| started_at | DATETIME | No | When publish began |
+| finished_at | DATETIME | No | When publish completed |
+| error_message | TEXT | No | Failure reason if applicable |
+| pages_copied | INTEGER | No | Number of pages published |
+| transitions_copied | INTEGER | No | Number of transitions published (legacy field, not currently populated) |
+| audios_copied | INTEGER | No | Number of audio tracks published |
+| projectId | UUID | Yes | FK to projects (CASCADE) |
+| userId | UUID | Yes | FK to users who initiated |
+
+### Status Lifecycle
+
+```
+queued → running → success
+                 ↘ failed
+```
+
+| Status | Meaning | Fields Set |
+|--------|---------|------------|
+| `queued` | Event created, waiting to process | title, description, environments |
+| `running` | Publish in progress | started_at |
+| `success` | Completed successfully | finished_at, *_copied counts |
+| `failed` | Encountered error | finished_at, error_message |
+
+### API Endpoints
+
+**Save to Stage (Dev → Stage):**
+```http
+POST /api/publish/save-to-stage
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "projectId": "uuid"
+}
+```
+
+**Response (Success):**
+```json
+{
+  "success": true,
+  "publishEventId": "uuid"
+}
+```
+
+**Note:** Save to Stage is **non-blocking** - the API returns immediately after creating the publish event, and the actual copy operation continues in the background. Check the `publish_events` table for final status (`success` or `failed`).
+
+**Publish to Production (Stage → Production):**
+
+*Note: Both `/api/publish` and `/api/publish/publish` route to the same handler.*
+
+```http
+POST /api/publish
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "projectId": "uuid",
+  "title": "Release 1.0.3",
+  "description": "Added new tour pages and fixed navigation"
+}
+```
+
+**Response (Success):**
+```json
+{
+  "success": true,
+  "publishEventId": "uuid",
+  "summary": {
+    "pages_copied": 5,
+    "audios_copied": 2
+  }
+}
+```
+
+**Publish Events CRUD:**
+```
+GET    /api/publish_events              - List with pagination
+GET    /api/publish_events/:id          - Get details
+PUT    /api/publish_events/:id          - Update
+DELETE /api/publish_events/:id          - Delete
+GET    /api/publish_events?project=id   - Filter by project
+```
+
+## Publishing Process
+
+### Blocking vs Non-Blocking Operations
+
+| Operation | Blocking | Behavior |
+|-----------|----------|----------|
+| **Save to Stage** | No | Returns immediately, copy runs in background via `setImmediate()` |
+| **Publish to Production** | Yes | Waits for entire copy operation before returning |
+
+**Save to Stage** uses background processing because it's a frequent operation during development and shouldn't block the UI. **Publish to Production** remains blocking because it's a deliberate action that users expect to complete before seeing results.
+
+### Complete Flow (Publish to Production)
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Phase 1: Validation & Event Creation                                    │
+├─────────────────────────────────────────────────────────────────────────┤
+│ POST /api/publish                                                       │
+│   ↓                                                                     │
+│ PublishService.publishToProduction()                                    │
+│   ├─ Validate projectId exists                                         │
+│   ├─ Validate title is non-empty                                       │
+│   ├─ Validate description is non-empty                                 │
+│   └─ CREATE publish_events record with status='queued'                 │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Phase 2: Acquire Lock & Begin Transaction                               │
+├─────────────────────────────────────────────────────────────────────────┤
+│ PublishService.withProjectPublishLock(projectId, callback)              │
+│   ├─ BEGIN TRANSACTION                                                  │
+│   ├─ SELECT * FROM projects WHERE id={id} FOR UPDATE                   │
+│   ├─ SELECT * FROM publish_events WHERE status='running' FOR UPDATE    │
+│   └─ If running publish exists → ERROR 400                             │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Phase 3: Copy Stage → Production                                        │
+├─────────────────────────────────────────────────────────────────────────┤
+│ 1. FETCH all stage data:                                                │
+│    ├─ tour_pages WHERE environment='stage'                             │
+│    ├─ project_audio_tracks WHERE environment='stage'                   │
+│    └─ project_transition_settings WHERE environment='stage'            │
+│                                                                         │
+│ 2. PURGE existing production data:                                      │
+│    ├─ DELETE tour_pages WHERE environment='production'                 │
+│    ├─ DELETE project_audio_tracks WHERE environment='production'       │
+│    └─ DELETE project_transition_settings WHERE environment='production'│
+│                                                                         │
+│ 3. CREATE production records via bulkCreate:                            │
+│    ├─ tour_pages (with environment='production', source_key tracking)  │
+│    ├─ project_audio_tracks                                             │
+│    └─ project_transition_settings (CSS transition defaults)            │
+│                                                                         │
+│ Note: Video transitions are stored in tour_pages.ui_schema_json and    │
+│       copied with the page. CSS transition settings (fade, duration,   │
+│       easing) are stored in project_transition_settings per environment.│
+│       Slugs are used for navigation (not IDs), so no remapping needed. │
+│                                                                         │
+│ Element defaults (element_type_defaults → project_element_defaults)    │
+│ are NOT environment-specific. Settings are embedded in elements when   │
+│ created, so ui_schema_json contains complete elements with settings.   │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Phase 4: Mark Success or Failure                                        │
+├─────────────────────────────────────────────────────────────────────────┤
+│ Success:                                                                │
+│   UPDATE publish_events SET status='success', finished_at=NOW(),       │
+│          pages_copied=N, audios_copied=N                               │
+│                                                                         │
+│ Failure:                                                                │
+│   UPDATE publish_events SET status='failed', finished_at=NOW(),        │
+│          error_message=error.message                                   │
+│   ROLLBACK TRANSACTION                                                  │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Data Copied During Publish
+
+**Entities Copied:**
+| Entity | Copied | Notes |
+|--------|--------|-------|
+| Tour Pages | ✅ | All stage pages → production (includes `sort_order`, `ui_schema_json` with elements, navigation, video transitions, and page media fields) |
+| Project Audio | ✅ | All stage audio → production |
+| Project Transition Settings | ✅ | CSS transition settings (type, duration, easing, overlay color) |
+
+**Entities NOT Copied:**
+| Entity | Reason |
+|--------|--------|
+| Assets | Shared across environments |
+| Project metadata | Name, slug, description unchanged |
+| User permissions | Independent of environment |
+| PWA caches | Generated separately |
+| Element type defaults | Global platform-wide (not project-specific) |
+| Project element defaults | Project-wide (not environment-specific) - settings are already embedded in elements within `ui_schema_json` when elements are created |
+
+### Page Order Propagation
+
+Page order is stored on `tour_pages.sort_order`. Runtime loaders sort pages by
+this field and use the first sorted page as the presentation entry page.
+
+The constructor can change the dev page set and order directly:
+
+- Reorder pages via `POST /api/tour_pages/reorder`. This updates only
+  `tour_pages.sort_order`.
+- Duplicate the active dev page via `POST /api/tour_pages/:id/duplicate`. This
+  creates a new independent dev page at the end of the order, copies page
+  settings and `ui_schema_json`, and regenerates inline element IDs.
+- Delete the active dev page via `DELETE /api/tour_pages/:id` after constructor
+  confirmation.
+
+Stage and production are intentionally read-only for direct constructor page
+writes:
+
+1. Reorder, duplicate, or delete pages in the constructor
+   (`environment='dev'`).
+2. Click Save to Stage to copy dev pages, including `sort_order`, to
+   `environment='stage'`.
+3. Publish to Production to copy stage pages, including `sort_order`, to
+   `environment='production'`.
+
+This means stage preview keeps the previous page set/order until Save to Stage
+finishes, and the public production presentation keeps the previous page set/order
+until Publish finishes.
+
+### Data Sanitization
+
+Before copying, records are sanitized:
+
+```javascript
+sanitizeRecordForClone(modelInstance) {
+  const data = modelInstance.toJSON();
+
+  // Delete auto-generated fields
+  delete data.id;           // Gets new UUID
+  delete data.createdAt;    // New timestamp
+  delete data.updatedAt;    // New timestamp
+  delete data.deletedAt;    // Not paranoid for production
+  delete data.deletedBy;    // Clear soft-delete actor
+  delete data.importHash;   // Unique field
+
+  // Ensure JSON fields are objects, not strings (avoid double-encoding)
+  if (data.ui_schema_json && typeof data.ui_schema_json === 'string') {
+    try {
+      data.ui_schema_json = JSON.parse(data.ui_schema_json);
+    } catch {
+      // Keep as-is if parsing fails
+    }
+  }
+
+  return data;
+}
+```
+
+## Transaction Locking
+
+### Concurrency Control
+
+The system prevents concurrent publishing using row-level locks:
+
+```javascript
+// Acquire exclusive lock on project row
+const project = await db.projects.findByPk(projectId, {
+  transaction,
+  lock: transaction.LOCK.UPDATE  // SELECT FOR UPDATE
+});
+
+// Check for running publish (also locked)
+const runningEvent = await db.publish_events.findOne({
+  where: { projectId, status: 'running' },
+  transaction,
+  lock: transaction.LOCK.UPDATE
+});
+
+if (runningEvent) {
+  throw Error('Publish already running for this project');
+}
+```
+
+### Lock Properties
+
+| Property | Value |
+|----------|-------|
+| **Isolation Level** | READ COMMITTED (Postgres default) |
+| **Lock Duration** | Transaction start → commit/rollback |
+| **Lock Scope** | Project row + publish_events rows |
+| **Deadlock Handling** | Auto-rollback on deadlock |
+| **Lock Timeout** | 5-30 seconds (DB config) |
+
+### Lock Workflow
+
+```
+1. Transaction Starts
+   └─ BEGIN TRANSACTION
+
+2. Acquire Project Lock
+   └─ SELECT * FROM projects WHERE id=? FOR UPDATE
+
+3. Check Running Publishes
+   └─ SELECT * FROM publish_events WHERE status='running' FOR UPDATE
+   └─ If exists → ROLLBACK + ERROR 400
+
+4. Execute Publish Operations
+   └─ All operations protected by transaction
+   └─ Concurrent requests block until lock released
+
+5. Commit or Rollback
+   └─ Success → COMMIT (locks released)
+   └─ Error → ROLLBACK (locks released)
+```
+
+### Error Handling
+
+**Pre-Lock Validation:**
+```javascript
+if (!projectId || !title || !description) {
+  throw new ValidationError('Missing required fields');
+  // No transaction started
+}
+```
+
+**Lock Conflict:**
+```javascript
+if (runningEvent) {
+  throw new ValidationError('Publish is already running for this project');
+  // HTTP 400 returned
+}
+```
+
+**Data Errors:**
+```javascript
+try {
+  await copyStageToProduction(projectId, userId, transaction);
+} catch (error) {
+  // Transaction automatically rolls back
+  // Error captured in publish_events.error_message
+  throw error;
+}
+```
+
+## Frontend Integration
+
+### Save to Stage Button (Constructor)
+
+**Files:**
+- `frontend/src/pages/constructor.tsx` - Uses the hook
+- `frontend/src/hooks/useConstructorPageActions.ts` - Contains the `saveToStage` implementation
+
+The Constructor uses the `useConstructorPageActions` hook which provides the `saveToStage` function:
+
+```typescript
+// hooks/useConstructorPageActions.ts
+const saveToStage = useCallback(async () => {
+  if (!projectId) {
+    onError?.('Project ID is required to save to stage.');
+    return;
+  }
+
+  // First save current state, then copy to stage
+  await saveConstructor();
+
+  try {
+    setIsSavingToStage(true);
+    // Note: axios baseURL adds '/api' prefix automatically
+    // Non-blocking: returns immediately, copy runs in background
+    await axios.post('/publish/save-to-stage', { projectId });
+    onSuccess?.('Saved to stage.');
+  } catch (error: any) {
+    onError?.(error?.response?.data?.message || 'Failed to save to stage');
+  } finally {
+    setIsSavingToStage(false);
+  }
+}, [projectId, saveConstructor, onError, onSuccess]);
+```
+
+**Note:** The Save to Stage operation is non-blocking - the button returns to normal immediately while the actual copy operation continues in the background. The user sees a brief "Saved to stage" confirmation.
+
+// constructor.tsx - Hook usage
+const {
+  isSavingToStage,
+  saveToStage,
+  // ... other actions
+} = useConstructorPageActions({
+  projectId,
+  pages,
+  // ... other options
+});
+
+// UI passes saveToStage to ConstructorMenu component
+<ConstructorMenu
+  onSaveToStage={saveToStage}
+  // ...
+/>
+```
+
+### Publish Status Visibility
+
+The platform displays timestamps showing when content was last saved or published, providing users with visual feedback on content freshness.
+
+#### usePublishStatus Hook
+
+**File:** `frontend/src/hooks/usePublishStatus.ts`
+
+Fetches the last successful publish events for a project:
+
+```typescript
+interface UsePublishStatusResult {
+  lastSavedToStage: string | null;        // Last dev → stage timestamp
+  lastPublishedToProduction: string | null; // Last stage → production timestamp
+  isLoading: boolean;
+  refresh: () => Promise<void>;           // Refresh after new publish
+}
+
+const { lastPublishedToProduction, refresh } = usePublishStatus({ projectId });
+```
+
+#### Timestamp Display
+
+Timestamps are displayed inside buttons using the `subtitle` prop of `BaseButton`:
+
+**Project Dashboard (Publish to Production):**
+```typescript
+<BaseButton
+  label={isPublishing ? 'Publishing...' : 'Publish to Production'}
+  subtitle={lastPublishedToProduction
+    ? `Last: ${dataFormatter.relativeTimestamp(lastPublishedToProduction)}`
+    : undefined}
+  color='success'
+  onClick={() => setIsPublishModalActive(true)}
+/>
+// Shows: "Publish to Production" with "Last: 5 min ago" below
+```
+
+**Constructor Menu (Save / Save to Stage):**
+```typescript
+// Project-level save timestamp: most recent updatedAt across all pages
+const lastProjectSaveAt = useMemo(() => {
+  if (!pages.length) return null;
+  return pages.reduce((latest, page) => {
+    if (!page.updatedAt) return latest;
+    if (!latest) return page.updatedAt;
+    return new Date(page.updatedAt) > new Date(latest) ? page.updatedAt : latest;
+  }, null as string | null);
+}, [pages]);
+
+<BaseButton
+  label={isSaving ? 'Saving...' : 'Save'}
+  subtitle={lastProjectSaveAt ? dataFormatter.relativeTimestamp(lastProjectSaveAt) : undefined}
+  onClick={onSave}
+/>
+// Shows: "Save" with project-level timestamp (same on all pages)
+```
+
+#### Relative Timestamp Format
+
+The `dataFormatter.relativeTimestamp()` method formats dates as human-readable relative times:
+
+| Time Difference | Display Format |
+|-----------------|----------------|
+| < 2 minutes | "Just now" |
+| < 60 minutes | "5 min ago" |
+| < 24 hours | "2 hours ago" |
+| Same day | "Today at 14:30" |
+| Yesterday | "Yesterday at 09:15" |
+| Older | "Apr 28 at 16:45" |
+
+### Publish Button (Project Dashboard)
+
+**File:** `frontend/src/pages/projects/[projectsId].tsx`
+
+```typescript
+const [isPublishing, setIsPublishing] = useState(false);
+const [isPublishModalActive, setIsPublishModalActive] = useState(false);
+const [publishTitle, setPublishTitle] = useState('');
+const [publishDescription, setPublishDescription] = useState('');
+
+// Publish status for timestamp display
+const { lastPublishedToProduction, refresh: refreshPublishStatus } = usePublishStatus({
+  projectId,
+});
+
+<BaseButton
+  label={isPublishing ? 'Publishing...' : 'Publish to Production'}
+  subtitle={lastPublishedToProduction
+    ? `Last: ${dataFormatter.relativeTimestamp(lastPublishedToProduction)}`
+    : undefined}
+  color='success'
+  onClick={() => setIsPublishModalActive(true)}
+  disabled={isPublishing || !projectId}
+/>
+```
+
+### Publish Modal
+
+```typescript
+<CardBoxModal
+  title='Publish to production'
+  buttonColor='success'
+  buttonLabel={isPublishing ? 'Publishing...' : 'Confirm publish'}
+  isConfirmDisabled={
+    isPublishing || !publishTitle.trim() || !publishDescription.trim()
+  }
+  isActive={isPublishModalActive}
+  onConfirm={handlePublish}
+  onCancel={() => { if (!isPublishing) setIsPublishModalActive(false); }}
+>
+  <FormField label='Event title'>
+    <input
+      placeholder='e.g. Release 1.0.3'
+      value={publishTitle}
+      onChange={(e) => setPublishTitle(e.target.value)}
+    />
+  </FormField>
+  <FormField label='Event description'>
+    <textarea
+      placeholder='Describe what was published'
+      value={publishDescription}
+      onChange={(e) => setPublishDescription(e.target.value)}
+    />
+  </FormField>
+</CardBoxModal>
+```
+
+### Publish Handler
+
+```typescript
+const handlePublish = async () => {
+  if (!projectId) {
+    toast('Project is required', { type: 'warning', position: 'bottom-center' });
+    return;
+  }
+
+  const title = publishTitle.trim();
+  const description = publishDescription.trim();
+
+  if (!title || !description) {
+    toast('Title and description are required', { type: 'warning', position: 'bottom-center' });
+    return;
+  }
+
+  setIsPublishing(true);
+  try {
+    // Note: axios baseURL adds '/api' prefix automatically
+    const response = await axios.post('/publish', {
+      projectId,
+      title,
+      description
+    });
+
+    const summary = response?.data?.summary;
+    toast(
+      summary
+        ? `Published: ${summary.pages_copied} pages`
+        : 'Publish completed successfully',
+      { type: 'success', position: 'bottom-center' }
+    );
+
+    setIsPublishModalActive(false);
+    setPublishTitle('');
+    setPublishDescription('');
+  } catch (error: any) {
+    const message = error?.response?.data || error?.message || 'Publish failed';
+    toast(typeof message === 'string' ? message : 'Publish failed', { type: 'error', position: 'bottom-center' });
+  } finally {
+    setIsPublishing(false);
+  }
+};
+```
+
+### Presentation Links
+
+```typescript
+const presentationLinks = useMemo(() => {
+  const projectSlug = project?.slug?.trim();
+  if (!projectSlug) return { production: '', stage: '' };
+
+  return {
+    production: `/p/${projectSlug}`,
+    stage: `/p/${projectSlug}/stage`,
+  };
+}, [project?.slug]);
+
+// UI buttons to open presentations (uses openPresentation helper)
+<BaseButton
+  label='To Production Presentation'
+  color='info'
+  onClick={() => openPresentation(presentationLinks.production, 'production presentation')}
+  disabled={!projectId || !project?.slug}
+/>
+<BaseButton
+  label='To Stage Presentation'
+  color='lightDark'
+  onClick={() => openPresentation(presentationLinks.stage, 'stage presentation')}
+  disabled={!projectId || !project?.slug}
+/>
+```
+
+## PWA Integration
+
+### Manifest Generation
+
+PWA manifests are generated separately from publishing:
+
+```http
+GET /api/projects/:id/offline-manifest?deviceType=desktop
+```
+
+**Response:**
+```json
+{
+  "version": "v1679856000000",
+  "projectId": "uuid",
+  "assets": [
+    {
+      "id": "asset-uuid",
+      "url": "/uploads/file.mp4",
+      "filename": "background.mp4",
+      "variantType": "mp4_high",
+      "assetType": "video",
+      "mimeType": "video/mp4",
+      "sizeBytes": 15000000,
+      "pageIds": ["page-uuid-1", "page-uuid-2"]
+    }
+  ],
+  "totalSizeBytes": 150000000,
+  "generatedAt": 1679856000000
+}
+```
+
+### PWA Cache Model
+
+**File:** `backend/src/db/models/pwa_caches.js`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | UUID | Primary key |
+| environment | ENUM | 'dev', 'stage', 'production' |
+| cache_version | TEXT | Version identifier |
+| manifest_json | JSON | Full manifest data |
+| asset_list_json | JSON | Asset URLs for caching |
+| generated_at | DATETIME | Generation timestamp |
+| is_active | BOOLEAN | Currently active cache |
+| projectId | UUID | FK to projects |
+
+### Relationship to Publishing
+
+- PWA manifests are **NOT** automatically regenerated on publish
+- Publishing copies data to production environment
+- PWA caches must be explicitly regenerated via separate API
+
+## Asset Preloading & Environment Filtering
+
+### How Preloading Respects Environments
+
+When viewing a tour in any environment, assets are preloaded only from pages in that environment. The filtering happens in the `usePageDataLoader` hook, and `RuntimePresentation` receives already-filtered pages:
+
+```typescript
+// usePageDataLoader.ts - Environment filtering during data load
+if (projectSlug) {
+  pageRows = pageRows.filter((p) => p.environment === environment);
+}
+pageRows.sort((a, b) => (a.sort_order ?? 0) - (b.sort_order ?? 0));
+
+// RuntimePresentation.tsx - Uses filtered pages from hook
+const { project, pages, isLoading, error, initialPageId } = usePageDataLoader({
+  projectSlug,
+  environment,
+  apiHeaders: {
+    'X-Runtime-Project-Slug': projectSlug,
+    'X-Runtime-Environment': environment,
+  },
+});
+
+// Extract navigation links only from same-environment pages
+const { pageLinks, preloadElements } = extractPageLinksAndElements(pages);
+
+// Preload orchestrator uses filtered pages
+const preloadOrchestrator = usePreloadOrchestrator({
+  pages,                  // Already filtered by environment
+  pageLinks,              // Navigation links with transitionVideoUrl
+  elements: preloadElements,
+  currentPageId: selectedPageId,
+  pageHistory,
+  enabled: !isLoading && !error,
+});
+```
+
+### S3 Presigned URLs for Assets
+
+Assets are downloaded directly from S3 using presigned URLs:
+
+```
+POST /api/file/presign
+{ urls: ["assets/project-x/image.jpg", ...] }
+→ Returns presigned URLs (1-hour expiry, max 50 per request)
+```
+
+This works identically across all environments since assets are project-scoped, not environment-scoped.
+
+### Instant Navigation with Preloaded Assets
+
+Navigation between pages uses pre-decoded blob URLs for instant display:
+
+```typescript
+const pageSwitch = usePageSwitch({
+  preloadCache: {
+    getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,  // O(1) instant lookup
+    getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+    preloadedUrls: preloadOrchestrator.preloadedUrls,
+  },
+});
+```
+
+This ensures smooth transitions regardless of environment (dev preview, stage, or production).
+
+**Manual Regeneration Pattern:**
+1. Admin publishes via "Publish to Production"
+2. Admin generates PWA manifest via separate action
+3. New manifest stored with `environment='production'`
+4. Previous manifest marked inactive
+
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| `backend/src/routes/publish.ts` | Publish API endpoints (save-to-stage, publish) |
+| `backend/src/services/publish.ts` | Publishing business logic |
+| `backend/src/db/models/publish_events.js` | Publish events model |
+| `backend/src/db/api/publish_events.ts` | Publish events DB operations |
+| `backend/src/db/api/runtime-context.ts` | Environment resolution from headers |
+| `backend/src/middlewares/runtime-context.ts` | Runtime environment detection |
+| `backend/src/services/pwa_manifest.js` | PWA manifest generation |
+| `frontend/src/pages/p/[projectSlug]/index.tsx` | Production presentation |
+| `frontend/src/pages/p/[projectSlug]/stage.tsx` | Stage presentation |
+| `frontend/src/pages/constructor.tsx` | Constructor with Save to Stage button |
+| `frontend/src/pages/projects/[projectsId].tsx` | Project dashboard with publish UI |
+| `frontend/src/pages/publish_events/*` | Publish events list/view pages |
+| `frontend/src/components/RuntimePresentation.tsx` | Runtime presentation component |
+| `frontend/src/hooks/usePageDataLoader.ts` | Data loading with environment filtering |
+| `frontend/src/hooks/useConstructorPageActions.ts` | Constructor actions (saveToStage) |
+| `frontend/src/hooks/usePublishStatus.ts` | Publish status timestamps |
+| `frontend/src/lib/extractPageLinks.ts` | Extract navigation links from pages |
+| `frontend/src/hooks/usePreloadOrchestrator.ts` | Asset preloading with ready blob URLs |
+| `frontend/src/hooks/usePageSwitch.ts` | Page navigation using preloaded assets |
+
+## Summary Table
+
+| Aspect | Dev | Stage | Production |
+|--------|-----|-------|------------|
+| **URL** | `/constructor?projectId=` | `/p/[slug]/stage` | `/p/[slug]` |
+| **Purpose** | Active editing | Preview/testing | Public access |
+| **Data Source** | `environment='dev'` | `environment='stage'` | `environment='production'` |
+| **Editing** | Full editing | Read-only | Read-only |
+| **Publish Action** | "Save to Stage" (non-blocking) → | "Publish to Production" (blocking) → | Final destination |
+| **PWA Cache** | Not applicable | Can be generated | Primary target |
+| **Visibility** | Constructor only | Stage URL | Public URL |
+
+## Troubleshooting
+
+### "Publish already running" Error
+
+1. Check `publish_events` table for `status='running'` records
+2. If stuck, manually update to `status='failed'`
+3. Check for database connection issues causing uncommitted transactions
+
+### Publishing Takes Too Long
+
+1. Check number of pages/elements being copied
+2. Review database performance
+3. Check for lock contention from concurrent operations
+
+### Production Data Not Updating
+
+1. Verify publish event completed with `status='success'`
+2. Check `pages_copied` count is non-zero
+3. Clear browser cache and reload presentation
+4. Verify correct project slug in URL
+
+### Stage/Production Mismatch
+
+1. Confirm stage data exists (`tour_pages WHERE environment='stage'`)
+2. Check publish event `error_message` for failures
+3. Review transaction logs for rollback issues
diff --git a/documentation/rbac-system.md b/documentation/rbac-system.md
new file mode 100644
index 0000000..4dc582e
--- /dev/null
+++ b/documentation/rbac-system.md
@@ -0,0 +1,803 @@
+# Role-Based Access Control (RBAC) System
+
+Complete documentation for the Tour Builder Platform's RBAC system including roles, permissions, custom permissions, and entity-level access control.
+
+## Overview
+
+The platform implements a comprehensive RBAC system with:
+- **7 Default Roles** - From Administrator to Public (seeded in database)
+- **54 Seeded Permissions** - CRUD operations for 13 entities + 2 special permissions
+- **Custom Permissions** - Per-user permissions independent of assigned role
+- **Middleware-based Enforcement** - Automatic permission checking on all routes
+
+> **Note:** The frontend TypeScript enum may define additional permissions not seeded in the backend. The seeder also assigns role-permissions for legacy entities (PAGE_ELEMENTS, PAGE_LINKS, TRANSITIONS) that were previously stored in separate tables but are now embedded in `tour_pages.ui_schema_json`.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              Request Flow                                │
+│                                                                          │
+│  Request → JWT Auth → Permission Middleware → Route Handler → Response  │
+│                           │                                              │
+│                           ▼                                              │
+│              ┌────────────────────────────┐                             │
+│              │    Permission Resolution    │                             │
+│              │                             │                             │
+│              │  1. AccessPolicy           │                             │
+│              │  2. Custom permissions     │                             │
+│              │  3. Role permissions       │                             │
+│              │  4. Public hardening       │                             │
+│              └────────────────────────────┘                             │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           Database Schema                                │
+│                                                                          │
+│  ┌─────────┐         ┌──────────────────────────┐         ┌───────────┐ │
+│  │  Users  │────────▶│ usersCustom_permissions  │◀────────│Permissions│ │
+│  └────┬────┘         │     Permissions          │         └─────┬─────┘ │
+│       │              └──────────────────────────┘               │       │
+│       │ app_roleId                                              │       │
+│       ▼                                                         │       │
+│  ┌─────────┐         ┌──────────────────────────┐               │       │
+│  │  Roles  │────────▶│  rolesPermissions        │◀──────────────┘       │
+│  └─────────┘         │     Permissions          │                       │
+│                      └──────────────────────────┘                       │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Database Models
+
+### Roles Model
+
+**File:** `backend/src/db/models/roles.js`
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| id | UUID | Yes | Primary key, auto-generated |
+| name | TEXT | Yes | Max 100 chars, role identifier |
+| role_customization | TEXT | No | JSON for custom role metadata |
+| importHash | STRING(255) | No | Unique, for CSV bulk imports |
+
+**Associations:**
+- `belongsToMany permissions` via `rolesPermissionsPermissions` junction table
+- `hasMany users` as `users_app_role` (FK: `app_roleId`)
+
+### Permissions Model
+
+**File:** `backend/src/db/models/permissions.js`
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| id | UUID | Yes | Primary key, auto-generated |
+| name | TEXT | Yes | Unique, max 100 chars, e.g., `READ_PROJECTS` |
+| importHash | STRING(255) | No | Unique, for CSV bulk imports |
+
+### Junction Tables
+
+**rolesPermissionsPermissions:**
+| Field | Type | Notes |
+|-------|------|-------|
+| roles_permissionsId | UUID | FK to roles, part of composite PK |
+| permissionId | UUID | FK to permissions, part of composite PK |
+
+**usersCustom_permissionsPermissions:**
+| Field | Type | Notes |
+|-------|------|-------|
+| users_custom_permissionsId | UUID | FK to users, part of composite PK |
+| permissionId | UUID | FK to permissions, part of composite PK |
+
+## Default Roles
+
+**File:** `backend/src/db/seeders/20200430130760-user-roles.js`
+
+| Role | Description | Typical Permissions |
+|------|-------------|---------------------|
+| **Administrator** | Full system access | All 54 seeded permissions + 12 legacy entity role assignments |
+| **Platform Owner** | Full CRUD on all entities | All entity CRUD operations |
+| **Account Manager** | Manages projects, users, assets | Create/Read/Update on most entities, including user creation and project page element defaults |
+| **Tour Designer** | Builds and designs tours | Full access to tour-related entities |
+| **Content Reviewer** | Reviews content | Read/Update on content entities |
+| **Analytics Viewer** | Views analytics and logs | Read-only access |
+| **Public** | Unauthenticated fallback and authenticated customer viewers | No seeded permissions; authenticated Public users can receive private production presentation grants |
+
+> **Note:** The seeder creates 7 roles. The Public role has no seeded permissions. Anonymous public runtime access uses the `RUNTIME_PUBLIC_READ_ENTITIES` bypass, while authenticated Public users can receive explicit private production presentation grants through `production_presentation_access`. Self-registration is disabled; new users are created by authorized staff through the Users flow. The "User" role is not seeded by default but can be created manually.
+
+## Permission Types
+
+### Seeded Entity Permissions (52 total)
+
+Each of the 13 entities has 4 CRUD permissions seeded in the database:
+
+```
+CREATE_{ENTITY}  - Create new records
+READ_{ENTITY}    - View/list records
+UPDATE_{ENTITY}  - Modify existing records
+DELETE_{ENTITY}  - Remove records
+```
+
+**Entities with CRUD permissions (seeded):**
+
+| Category | Entities |
+|----------|----------|
+| **System** | users, roles, permissions |
+| **Projects** | projects, project_memberships |
+| **Assets** | assets, asset_variants |
+| **Tours** | tour_pages (elements, navigation, transitions stored in ui_schema_json) |
+| **Media** | project_audio_tracks |
+| **Publishing** | publish_events, pwa_caches |
+| **Access** | presigned_url_requests, access_logs |
+
+> **Note:** `element_type_defaults` and `project_element_defaults` permissions are **not seeded** but can be created manually if needed. The frontend enum and documentation may reference these for completeness.
+
+### Legacy Entity Permissions (assigned to roles but not seeded as permission records)
+
+The seeder assigns role-permissions for these legacy entities, which were previously stored in separate tables:
+
+| Entity | Current Status |
+|--------|----------------|
+| page_elements | Now stored in `tour_pages.ui_schema_json` |
+| page_links | Now stored in `tour_pages.ui_schema_json` |
+| transitions | Now stored on navigation elements in `ui_schema_json` |
+
+These permission names (e.g., `READ_PAGE_ELEMENTS`) are referenced in role assignments and the `RUNTIME_PUBLIC_READ_ENTITIES` set for backward compatibility. Project element defaults use `PAGE_ELEMENTS` permissions:
+
+| Role | PAGE_ELEMENTS Permissions |
+|------|---------------------------|
+| Administrator | Create, Read, Update, Delete |
+| Platform Owner | Create, Read, Update, Delete |
+| Account Manager | Create, Read, Update |
+| Tour Designer | Create, Read, Update |
+| Content Reviewer | Read, Update |
+| Analytics Viewer | Read |
+| Public | None |
+
+### Special Permissions (2 seeded)
+
+| Permission | Purpose | Seeded |
+|------------|---------|--------|
+| `READ_API_DOCS` | Access Swagger API documentation | ✅ Yes |
+| `CREATE_SEARCH` | Execute global search queries | ✅ Yes |
+
+**Total seeded permissions:** 13 entities × 4 CRUD + 2 special = **54 permissions**
+
+### Frontend Permission Enum
+
+**File:** `frontend/src/types/permissions.ts`
+
+The frontend enum defines all permissions used in UI permission checks. Note that some permissions in this enum are **not seeded** in the backend but are included for potential future use or manual creation:
+
+```typescript
+enum Permission {
+  // Users
+  CREATE_USERS = 'CREATE_USERS',
+  READ_USERS = 'READ_USERS',
+  UPDATE_USERS = 'UPDATE_USERS',
+  DELETE_USERS = 'DELETE_USERS',
+
+  // Projects
+  CREATE_PROJECTS = 'CREATE_PROJECTS',
+  READ_PROJECTS = 'READ_PROJECTS',
+  UPDATE_PROJECTS = 'UPDATE_PROJECTS',
+  DELETE_PROJECTS = 'DELETE_PROJECTS',
+
+  // ... similar pattern for all seeded entities (13 entities × 4 = 52 permissions)
+
+  // Legacy entities (stored in ui_schema_json, permissions assigned to roles)
+  READ_PAGE_ELEMENTS = 'READ_PAGE_ELEMENTS',
+  CREATE_PAGE_ELEMENTS = 'CREATE_PAGE_ELEMENTS',
+  // ... similar for PAGE_LINKS, TRANSITIONS
+
+  // UI Elements (NOT seeded in backend)
+  READ_UI_ELEMENTS = 'READ_UI_ELEMENTS',
+  CREATE_UI_ELEMENTS = 'CREATE_UI_ELEMENTS',
+  UPDATE_UI_ELEMENTS = 'UPDATE_UI_ELEMENTS',
+  DELETE_UI_ELEMENTS = 'DELETE_UI_ELEMENTS',
+}
+
+// Helper to get CRUD permissions for an entity
+export const getEntityPermissions = (entityName: string) => {
+  const uppercased = entityName.toUpperCase();
+  return {
+    read: `READ_${uppercased}`,
+    create: `CREATE_${uppercased}`,
+    update: `UPDATE_${uppercased}`,
+    delete: `DELETE_${uppercased}`,
+  };
+};
+```
+
+**Frontend vs Backend Permissions:**
+
+| Permission Type | Frontend Enum | Backend Seeded |
+|-----------------|---------------|----------------|
+| 13 core entities | ✅ | ✅ |
+| PAGE_ELEMENTS, PAGE_LINKS, TRANSITIONS | ✅ | Role assignments only |
+| UI_ELEMENTS | ✅ | ❌ Not seeded |
+| READ_API_DOCS, CREATE_SEARCH | ❌ | ✅ |
+
+> **Note:** The frontend `hasPermission` helper bypasses permission checks for the Administrator role (single permission checks only).
+
+## Custom Permissions
+
+Users can have permissions beyond their assigned role through custom permissions.
+
+### User-Permission Association
+
+**File:** `backend/src/db/models/users.js`
+
+```javascript
+db.users.belongsToMany(db.permissions, {
+  as: 'custom_permissions',
+  foreignKey: { name: 'users_custom_permissionsId' },
+  through: 'usersCustom_permissionsPermissions',
+  onDelete: 'CASCADE',
+});
+```
+
+### Setting Custom Permissions
+
+**Create User with Custom Permissions:**
+```javascript
+await UsersDBApi.create({
+  data: {
+    email: 'user@example.com',
+    app_role: roleId,
+    custom_permissions: [permissionId1, permissionId2]
+  }
+}, options);
+```
+
+**Update User's Custom Permissions:**
+```javascript
+await UsersDBApi.update({
+  id: userId,
+  data: {
+    custom_permissions: [permissionId1, permissionId2, permissionId3],
+  },
+  ...options,
+});
+```
+
+### Effective Permissions
+
+A user's effective permissions are the **union** of:
+1. Permissions from their assigned role (`app_role.permissions`)
+2. Their custom permissions (`custom_permissions`)
+
+```
+Effective Permissions = Role Permissions ∪ Custom Permissions
+```
+
+`Public` access is an explicit exception for admin API access: even if stale
+role/custom permissions exist in the database, `AccessPolicy.hasPermission`
+returns `false` for authenticated `Public` users and
+`AccessPolicy.getRolePermissionNames()` ignores permissions on the `Public`
+role fallback. Private presentation access for customer viewers is stored
+separately in `production_presentation_access`.
+
+## Access Policy
+
+**File:** `backend/src/services/access-policy.ts`
+
+Centralized access helper used by permission middleware and runtime
+presentation access:
+
+| Method | Purpose |
+|--------|---------|
+| `hasPermission(user, permission)` | Checks effective RBAC permission for non-Public users |
+| `isPublicUser(user)` | Detects authenticated customer viewer users |
+| `isInternalUser(user)` | Detects authenticated non-Public users |
+| `isPlatformWideRole(user)` | Checks Administrator, Platform Owner, Account Manager |
+| `canUseAdminApi(user)` | Allows only non-Public users with at least one RBAC permission |
+| `canViewProductionPresentation(user, projectSlug)` | Allows public presentations, internal staff, or explicit private grants |
+
+### Public Access Hardening Audit
+
+**Service:** `backend/src/services/access-policy-audit.ts`
+
+**CLI:**
+
+```bash
+cd backend
+npm run check:public-access       # read-only audit, exits 1 when violations exist
+npm run fix:public-access         # removes stale Public grants
+```
+
+The audit checks:
+
+- permissions assigned to any role named `Public`
+- custom permissions assigned to users whose role is `Public`
+- `production_presentation_access` rows assigned to non-Public users
+
+The cleanup command removes only those stale grants. Runtime access remains
+controlled by `AccessPolicy` even before cleanup, so stale Public permissions do
+not authorize admin API access.
+
+## Permission Middleware
+
+**File:** `backend/src/middlewares/check-permissions.ts`
+
+### Permission Resolution Order
+
+```javascript
+const checkPermissions = (permission) => async (req, res, next) => {
+  const currentUser = req.currentUser;
+
+  if (await AccessPolicy.hasPermission(currentUser, permission)) {
+    return next();
+  }
+
+  // Public role fallback for unauthenticated/no-role reads
+  const effectiveRole = currentUser?.app_role || publicRoleCache;
+  const rolePermissionNames = await AccessPolicy.getRolePermissionNames(effectiveRole);
+  if (rolePermissionNames.has(permission)) {
+    return next();
+  }
+
+  throw new ForbiddenError();
+};
+```
+
+Self-access bypass is intentionally narrow: only authenticated users can access
+their own `/api/users/:id` for `GET`, `PUT`, and `PATCH`. Other entities always
+use normal permission checks, and route params are the canonical id.
+
+### Tests
+
+```bash
+cd backend
+npm run test
+npm run test:integration
+```
+
+Unit tests cover effective permission merging, Public admin API denial,
+internal admin API access, and platform-wide role detection. Integration tests
+use a rollback transaction against a real PostgreSQL database when available;
+they cover guest runtime access, granted Public private presentation access,
+internal private presentation access, and audit cleanup.
+
+### CRUD Permission Mapping
+
+```javascript
+const METHOD_MAP = {
+  POST: 'CREATE',
+  GET: 'READ',
+  PUT: 'UPDATE',
+  PATCH: 'UPDATE',
+  DELETE: 'DELETE',
+};
+
+// Example: PUT /api/projects/123 → 'UPDATE_PROJECTS'
+const permissionName = `${METHOD_MAP[req.method]}_${entityName.toUpperCase()}`;
+```
+
+### Public Runtime Access
+
+Certain entities are readable without authentication for published tours:
+
+```javascript
+const RUNTIME_PUBLIC_READ_ENTITIES = new Set([
+  'PROJECTS',
+  'TOUR_PAGES',
+  'PAGE_ELEMENTS',
+  'PAGE_LINKS',
+  'TRANSITIONS',
+  'PROJECT_AUDIO_TRACKS'
+]);
+```
+
+When `req.isRuntimePublicRequest === true` and method is `GET`, these bypass permission checks.
+
+Private production presentations still use `req.isRuntimePublicRequest` after
+the user passes staff permission or `production_presentation_access` checks.
+This lets Public-role customer users read runtime-safe data without granting
+broad permissions such as `READ_PROJECTS` or `READ_TOUR_PAGES`. See
+[private-production-presentations.md](./private-production-presentations.md).
+
+## Router Factory Integration
+
+**File:** `backend/src/factories/router.factory.js`
+
+All entity routes automatically apply permission checking:
+
+```javascript
+function createEntityRouter(entityName, Service, DBApi, options = {}) {
+  const router = express.Router();
+
+  // Permission entity can be customized
+  const permissionEntity = options.permissionEntity || entityName;
+
+  // Apply permission middleware to all routes
+  router.use(checkCrudPermissions(permissionEntity));
+
+  // CRUD routes automatically protected
+  router.post('/', ...);       // Requires CREATE_ENTITY
+  router.get('/', ...);        // Requires READ_ENTITY
+  router.get('/:id', ...);     // Requires READ_ENTITY
+  router.put('/:id', ...);     // Requires UPDATE_ENTITY
+  router.delete('/:id', ...);  // Requires DELETE_ENTITY
+
+  return router;
+}
+```
+
+## API Endpoints
+
+### Roles Routes
+
+| Method | Endpoint | Permission | Description |
+|--------|----------|------------|-------------|
+| POST | `/api/roles` | CREATE_ROLES | Create new role |
+| GET | `/api/roles` | READ_ROLES | List roles with pagination |
+| GET | `/api/roles/:id` | READ_ROLES | Get role by ID |
+| PUT | `/api/roles/:id` | UPDATE_ROLES | Update role |
+| DELETE | `/api/roles/:id` | DELETE_ROLES | Delete role |
+| POST | `/api/roles/deleteByIds` | DELETE_ROLES | Bulk delete |
+| POST | `/api/roles/bulk-import` | CREATE_ROLES | CSV import |
+| GET | `/api/roles/count` | READ_ROLES | Total count |
+| GET | `/api/roles/autocomplete` | READ_ROLES | Autocomplete |
+
+**Create/Update Request:**
+```json
+{
+  "data": {
+    "name": "Custom Role",
+    "role_customization": "{}",
+    "permissions": ["permission-uuid-1", "permission-uuid-2"]
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "id": "uuid",
+  "name": "Custom Role",
+  "role_customization": "{}",
+  "permissions": [
+    { "id": "uuid", "name": "CREATE_PROJECTS" },
+    { "id": "uuid", "name": "READ_PROJECTS" }
+  ],
+  "createdAt": "2025-01-01T00:00:00Z",
+  "updatedAt": "2025-01-01T00:00:00Z"
+}
+```
+
+### Permissions Routes
+
+| Method | Endpoint | Permission | Description |
+|--------|----------|------------|-------------|
+| POST | `/api/permissions` | CREATE_PERMISSIONS | Create permission |
+| GET | `/api/permissions` | READ_PERMISSIONS | List permissions |
+| GET | `/api/permissions/:id` | READ_PERMISSIONS | Get by ID |
+| PUT | `/api/permissions/:id` | UPDATE_PERMISSIONS | Update |
+| DELETE | `/api/permissions/:id` | DELETE_PERMISSIONS | Delete |
+| POST | `/api/permissions/deleteByIds` | DELETE_PERMISSIONS | Bulk delete |
+| POST | `/api/permissions/bulk-import` | CREATE_PERMISSIONS | CSV import |
+| GET | `/api/permissions/autocomplete` | READ_PERMISSIONS | Autocomplete |
+
+### User Permission Management
+
+**Assign Role and Custom Permissions (via Users API):**
+
+```http
+PUT /api/users/:id
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "data": {
+    "app_role": "role-uuid",
+    "custom_permissions": ["perm-uuid-1", "perm-uuid-2"]
+  }
+}
+```
+
+**Get Current User with Permissions:**
+
+```http
+GET /api/auth/me
+Authorization: Bearer {token}
+```
+
+**Response:**
+```json
+{
+  "id": "user-uuid",
+  "email": "admin@flatlogic.com",
+  "firstName": "Admin",
+  "app_role": {
+    "id": "role-uuid",
+    "name": "Administrator",
+    "permissions": [
+      { "id": "perm-uuid", "name": "CREATE_USERS" },
+      { "id": "perm-uuid", "name": "READ_USERS" }
+    ]
+  },
+  "custom_permissions": [
+    { "id": "perm-uuid", "name": "CREATE_SEARCH" }
+  ]
+}
+```
+
+## Frontend Implementation
+
+### Permission Helper
+
+**File:** `frontend/src/helpers/userPermissions.ts`
+
+```typescript
+export function hasPermission(
+  user: UserWithPermissions,
+  permission_name: string | string[]
+): boolean {
+  if (!user?.app_role?.name) return false;
+  if (!permission_name) return true;
+
+  // Combine custom permissions and role permissions
+  const permissions = new Set<string>([
+    ...(user?.custom_permissions ?? []).map((p) => p.name),
+    ...(user?.app_role?.permissions ?? []).map((p) => p.name),
+  ]);
+
+  if (typeof permission_name === 'string') {
+    // Single permission: check permission OR Administrator role
+    return (
+      permissions.has(permission_name) || user.app_role.name === 'Administrator'
+    );
+  } else {
+    // Multiple permissions: OR logic (Administrator bypass NOT applied here!)
+    return permission_name.some((p) => permissions.has(p));
+  }
+}
+```
+
+> **Important:** The Administrator bypass only applies to **single permission** checks. When checking an array of permissions, the Administrator role does NOT automatically pass - the user must have at least one of the specified permissions.
+
+### Usage Examples
+
+**Single Permission Check:**
+```typescript
+import { hasPermission } from '@/helpers/userPermissions';
+
+function EditButton({ user, projectId }) {
+  if (!hasPermission(user, 'UPDATE_PROJECTS')) {
+    return null;
+  }
+  return <button>Edit Project</button>;
+}
+```
+
+**Multiple Permissions (OR logic):**
+```typescript
+function AdminPanel({ user }) {
+  if (!hasPermission(user, ['UPDATE_USERS', 'DELETE_USERS'])) {
+    return <AccessDenied />;
+  }
+  return <UserManagement />;
+}
+```
+
+**Conditional Rendering:**
+```typescript
+function ProjectActions({ user, project }) {
+  return (
+    <div>
+      {hasPermission(user, 'READ_PROJECTS') && (
+        <ViewButton project={project} />
+      )}
+      {hasPermission(user, 'UPDATE_PROJECTS') && (
+        <EditButton project={project} />
+      )}
+      {hasPermission(user, 'DELETE_PROJECTS') && (
+        <DeleteButton project={project} />
+      )}
+    </div>
+  );
+}
+```
+
+### Redux Integration
+
+**File:** `frontend/src/stores/permissions/permissionsSlice.ts`
+
+```typescript
+// Fetch all permissions
+dispatch(permissionsActions.fetch({ query: '' }));
+
+// Create new permission
+dispatch(permissionsActions.create({
+  data: { name: 'READ_CUSTOM_ENTITY' }
+}));
+
+// Delete permission
+dispatch(permissionsActions.deleteItem(permissionId));
+```
+
+## Seeding Process
+
+**File:** `backend/src/db/seeders/20200430130760-user-roles.js`
+
+### Step 1: Create Roles
+
+```javascript
+await queryInterface.bulkInsert("roles", [
+  { id: getId("Administrator"), name: "Administrator" },
+  { id: getId("PlatformOwner"), name: "Platform Owner" },
+  { id: getId("AccountManager"), name: "Account Manager" },
+  { id: getId("TourDesigner"), name: "Tour Designer" },
+  { id: getId("ContentReviewer"), name: "Content Reviewer" },
+  { id: getId("AnalyticsViewer"), name: "Analytics Viewer" },
+  { id: getId("Public"), name: "Public" },
+]);
+```
+
+### Step 2: Create Permissions
+
+```javascript
+const entities = [
+  "users", "roles", "permissions", "projects", "project_memberships",
+  "assets", "asset_variants", "presigned_url_requests", "tour_pages",
+  "project_audio_tracks", "publish_events", "pwa_caches", "access_logs"
+];
+
+// Generate CRUD permissions for each entity (13 × 4 = 52 permissions)
+const permissions = entities.flatMap(name => [
+  { name: `CREATE_${name.toUpperCase()}` },
+  { name: `READ_${name.toUpperCase()}` },
+  { name: `UPDATE_${name.toUpperCase()}` },
+  { name: `DELETE_${name.toUpperCase()}` }
+]);
+
+// Add special permissions (+2 = 54 total)
+permissions.push(
+  { name: 'READ_API_DOCS' },
+  { name: 'CREATE_SEARCH' }
+);
+```
+
+### Step 3: Assign Permissions to Roles
+
+```javascript
+// Administrator gets all permissions
+// Other roles get specific subsets
+
+const rolePermissionMap = {
+  "PlatformOwner": ["CREATE_*", "READ_*", "UPDATE_*", "DELETE_*"],
+  "AccountManager": ["READ_USERS", "UPDATE_USERS", "CREATE_PROJECTS", ...],
+  "TourDesigner": ["READ_PROJECTS", "UPDATE_TOUR_PAGES", ...],
+  "ContentReviewer": ["READ_PROJECTS", "UPDATE_PAGE_ELEMENTS", ...],
+  "AnalyticsViewer": ["READ_*"],
+  "Public": ["READ_PROJECTS", "READ_TOUR_PAGES", ...],
+};
+```
+
+## Complete Permission Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    PUT /api/projects/:id                         │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│              Passport JWT Authentication                         │
+│  - Extract Bearer token from Authorization header               │
+│  - Verify JWT signature and expiry                              │
+│  - Load user from DB with app_role and custom_permissions       │
+│  - Set req.currentUser                                          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│           checkCrudPermissions('projects')                       │
+│  - Map PUT method → 'UPDATE'                                    │
+│  - Generate permission: 'UPDATE_PROJECTS'                       │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│             checkPermissions('UPDATE_PROJECTS')                  │
+│                                                                  │
+│  Step 1: Self-access check                                      │
+│    └── currentUser.id === req.params.id? → PASS                 │
+│                                                                  │
+│  Step 2: Custom permissions check                               │
+│    └── custom_permissions.includes('UPDATE_PROJECTS')? → PASS   │
+│                                                                  │
+│  Step 3: Role permissions check                                 │
+│    └── app_role.permissions.includes('UPDATE_PROJECTS')? → PASS │
+│                                                                  │
+│  Step 4: Deny                                                   │
+│    └── Throw ValidationError('auth.forbidden') → 403            │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Route Handler                                │
+│  - Execute ProjectsService.update()                             │
+│  - Return updated project                                       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| `backend/src/db/models/roles.js` | Role model definition |
+| `backend/src/db/models/permissions.js` | Permission model definition |
+| `backend/src/db/models/users.js` | User-role and user-permission associations |
+| `backend/src/db/api/roles.ts` | Roles database operations |
+| `backend/src/db/api/permissions.ts` | Permissions database operations |
+| `backend/src/db/seeders/20200430130760-user-roles.js` | Default roles/permissions seeder |
+| `backend/src/middlewares/check-permissions.ts` | Permission enforcement middleware |
+| `backend/src/factories/router.factory.js` | Auto-applies permissions to routes |
+| `backend/src/routes/roles.ts` | Roles API routes |
+| `backend/src/routes/permissions.ts` | Permissions API routes |
+| `frontend/src/helpers/userPermissions.ts` | Client-side permission helper |
+| `frontend/src/types/permissions.ts` | TypeScript Permission enum |
+| `frontend/src/stores/permissions/permissionsSlice.ts` | Redux state for permissions |
+
+## Best Practices
+
+### Creating New Permissions
+
+1. **Add to seeder** for new installations
+2. **Create migration** for existing installations
+3. **Update TypeScript enum** in frontend
+4. **Assign to appropriate roles**
+
+### Checking Permissions in Code
+
+**Backend:**
+```javascript
+// Automatic via router factory - no manual check needed
+// For custom endpoints:
+router.get('/custom', checkPermissions('READ_CUSTOM'), handler);
+```
+
+**Frontend:**
+```typescript
+// Always use hasPermission helper
+if (hasPermission(user, 'UPDATE_PROJECTS')) {
+  // Render UI element
+}
+```
+
+### Administrator Role
+
+The Administrator role has special handling in the `hasPermission` helper:
+
+```typescript
+// Single permission check - Administrator bypass applied
+hasPermission(adminUser, 'UPDATE_PROJECTS')  // → true (always)
+
+// Multiple permission check - Administrator bypass NOT applied
+hasPermission(adminUser, ['UPDATE_USERS', 'DELETE_USERS'])  // → depends on actual permissions
+```
+
+> **Note:** The Administrator bypass only works for single permission (string) checks. For array checks, Administrator users must have at least one of the permissions in their role or custom permissions.
+
+## Troubleshooting
+
+### "auth.forbidden" Error
+
+1. Check user has required permission via `/api/auth/me`
+2. Verify role has permission assigned
+3. Check custom_permissions array
+4. Ensure JWT token is valid and not expired
+
+### Permission Not Working After Adding
+
+1. Re-run seeder or create migration
+2. Clear any caches
+3. Re-fetch user data (`dispatch(findMe())`)
+4. Verify permission name matches exactly (case-sensitive)
+
+### Public Access Issues
+
+1. Verify entity is in `RUNTIME_PUBLIC_READ_ENTITIES`
+2. Check `isRuntimePublicRequest` is set correctly
+3. Ensure Public role has required permissions
diff --git a/documentation/search-system.md b/documentation/search-system.md
new file mode 100644
index 0000000..03b3337
--- /dev/null
+++ b/documentation/search-system.md
@@ -0,0 +1,509 @@
+# Search System
+
+Complete documentation for the Tour Builder Platform's global full-text search system with permission-based filtering.
+
+## Overview
+
+The platform implements a global search service that performs full-text search across multiple database tables simultaneously. Results are filtered based on the current user's permissions, ensuring users only see data they have access to.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        Search System Architecture                            │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                         Search Request                                  │ │
+│  │                                                                         │ │
+│  │   POST /api/search                                                      │ │
+│  │   { searchQuery: "vacation" }                                          │ │
+│  │              │                                                          │ │
+│  │              ▼                                                          │ │
+│  │   ┌─────────────────────────────────────────────────────────────────┐  │ │
+│  │   │              Permission Check (checkCrudPermissions)            │  │ │
+│  │   │                                                                  │  │ │
+│  │   │   READ_SEARCH permission required                               │  │ │
+│  │   └──────────────────────────┬──────────────────────────────────────┘  │ │
+│  │                              ▼                                          │ │
+│  │   ┌─────────────────────────────────────────────────────────────────┐  │ │
+│  │   │                    SearchService.search()                        │  │ │
+│  │   │                                                                  │  │ │
+│  │   │   For each table:                                               │  │ │
+│  │   │   1. Check READ_<TABLE> permission                              │  │ │
+│  │   │   2. If allowed, search text + numeric columns                  │  │ │
+│  │   │   3. Return up to 50 matching records                           │  │ │
+│  │   └──────────────────────────┬──────────────────────────────────────┘  │ │
+│  │                              ▼                                          │ │
+│  │   ┌─────────────────────────────────────────────────────────────────┐  │ │
+│  │   │                     Search Results                               │  │ │
+│  │   │                                                                  │  │ │
+│  │   │   [{ id, tableName, matchAttribute, ...record }]                │  │ │
+│  │   └─────────────────────────────────────────────────────────────────┘  │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## API Reference
+
+### Endpoint
+
+**URL:** `POST /api/search`
+
+**Authentication:** Required (JWT)
+
+**Permission:** `READ_SEARCH`
+
+**Source:** `backend/src/routes/search.ts`
+
+### Request Format
+
+```json
+POST /api/search
+Content-Type: application/json
+Authorization: Bearer <jwt-token>
+
+{
+  "searchQuery": "vacation tour"
+}
+```
+
+### Response Format
+
+```json
+[
+  {
+    "id": "uuid-1",
+    "name": "Vacation Paradise Tour",
+    "slug": "vacation-paradise",
+    "tableName": "projects",
+    "matchAttribute": ["name", "slug"]
+  },
+  {
+    "id": "uuid-2",
+    "name": "Beach Vacation Page",
+    "slug": "beach-vacation",
+    "tableName": "tour_pages",
+    "matchAttribute": ["name"]
+  }
+]
+```
+
+### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Record's unique identifier |
+| `tableName` | string | Source table name |
+| `matchAttribute` | string[] | Array of field names that matched the query |
+| `...record` | object | All searchable fields from the record |
+
+### Error Responses
+
+| Status | Error | Description |
+|--------|-------|-------------|
+| 400 | "Please enter a search query" | Missing searchQuery in request body |
+| 401 | Unauthorized | Missing or invalid JWT token |
+| 403 | Forbidden | User lacks READ_SEARCH permission |
+| 500 | "Internal Server Error" | Database or server error |
+
+## Search Service
+
+**Source:** `backend/src/services/search.ts`
+
+### Core Logic
+
+```typescript
+export default class SearchService {
+  static async search(searchQuery: string, currentUser: CurrentUser | undefined): Promise<SearchResult> {
+    // 1. Validate search query
+    if (!searchQuery) {
+      throw new ValidationError('iam.errors.searchQueryRequired');
+    }
+
+    // 2. Get user's permissions
+    const permissionSet = await getUserPermissions(currentUser);
+
+    // 3. Search each table in parallel
+    const searchTasks = searchTables.map(async ({ tableName, textColumns }) => {
+      // Skip if user lacks READ permission for this table
+      if (!hasPermission(permissionSet, `READ_${tableName.toUpperCase()}`)) {
+        return [];
+      }
+
+      // Perform case-insensitive search
+      const model = db[tableName];
+      if (!isSearchModel(model)) {
+        return [];
+      }
+
+      const foundRecords = await model.findAll({
+        where: { [Op.or]: [...searchConditions] },
+        limit: 50,
+      });
+
+      return foundRecords.map(record => ({
+        ...record.get(),
+        matchAttribute,
+        tableName,
+      }));
+    });
+
+    return (await Promise.all(searchTasks)).flat();
+  }
+}
+```
+
+### Search Configuration
+
+```javascript
+const SEARCH_LIMIT_PER_TABLE = 50;  // Max results per table
+```
+
+## Searchable Tables
+
+### Text Columns (String Search)
+
+| Table | Searchable Columns |
+|-------|-------------------|
+| `users` | firstName, lastName, phoneNumber, email |
+| `projects` | name, slug, description, logo_url, favicon_url, og_image_url |
+| `assets` | name, cdn_url, storage_key, mime_type, checksum |
+| `asset_variants` | cdn_url |
+| `presigned_url_requests` | requested_key, mime_type, status |
+| `tour_pages` | source_key, name, slug, background_image_url, background_video_url, background_audio_url, ui_schema_json |
+| `project_audio_tracks` | source_key, name, slug, url |
+| `publish_events` | error_message |
+| `pwa_caches` | cache_version, manifest_json, asset_list_json |
+| `access_logs` | path, ip_address, user_agent |
+
+### Numeric Columns (Cast to String)
+
+| Table | Searchable Columns |
+|-------|-------------------|
+| `assets` | size_mb, width_px, height_px, duration_sec |
+| `asset_variants` | width_px, height_px, size_mb |
+| `presigned_url_requests` | requested_size_mb |
+| `tour_pages` | sort_order |
+| `project_audio_tracks` | volume, sort_order |
+| `publish_events` | pages_copied, transitions_copied, audios_copied |
+
+## Permission-Based Filtering
+
+### How It Works
+
+The search system implements two levels of permission checking:
+
+1. **Route-Level:** `READ_SEARCH` permission required to access the endpoint
+2. **Table-Level:** `READ_<TABLE>` permission required for each table
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    Permission-Based Search Filtering                         │
+│                                                                              │
+│  User with permissions: [READ_SEARCH, READ_PROJECTS, READ_TOUR_PAGES]       │
+│                                                                              │
+│  Search Query: "beach"                                                       │
+│                                                                              │
+│  ┌──────────────────────────────────────────────────────────────────────┐   │
+│  │ Table              │ Permission Required    │ Searched? │ Results   │   │
+│  ├──────────────────────────────────────────────────────────────────────┤   │
+│  │ users              │ READ_USERS             │ ✗ Skipped │ -         │   │
+│  │ projects           │ READ_PROJECTS          │ ✓ Yes     │ 3 matches │   │
+│  │ assets             │ READ_ASSETS            │ ✗ Skipped │ -         │   │
+│  │ tour_pages         │ READ_TOUR_PAGES        │ ✓ Yes     │ 5 matches │   │
+│  │ project_audio_tracks│ READ_PROJECT_AUDIO_TRACKS│ ✗ Skipped │ -       │   │
+│  │ ...                │ ...                    │ ...       │ ...       │   │
+│  └──────────────────────────────────────────────────────────────────────┘   │
+│                                                                              │
+│  Total Results: 8 (only from projects + tour_pages)                         │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Permission Resolution
+
+**Source:** `backend/src/services/search.ts`
+
+```javascript
+async function getUserPermissions(currentUser) {
+  if (!currentUser) {
+    throw new ValidationError('auth.unauthorized');
+  }
+
+  const permissions = new Set(
+    (currentUser.custom_permissions || [])
+      .map((cp) => cp.name)
+      .filter(Boolean),
+  );
+
+  if (!currentUser.app_role) {
+    throw new ValidationError('auth.forbidden');
+  }
+
+  // Add role-based permissions
+  const rolePermissions = await currentUser.app_role.getPermissions();
+  for (const permission of rolePermissions) {
+    if (permission?.name) {
+      permissions.add(permission.name);
+    }
+  }
+
+  return permissions;
+}
+```
+
+### Permission Sources
+
+| Source | Description |
+|--------|-------------|
+| `currentUser.custom_permissions` | User-specific permission overrides |
+| `currentUser.app_role.getPermissions()` | Permissions inherited from assigned role |
+
+## Search Algorithm
+
+### Case-Insensitive Matching
+
+The search uses PostgreSQL's `ILIKE` operator for case-insensitive partial matching:
+
+```javascript
+// Text columns: direct ILIKE
+{
+  [attribute]: {
+    [Op.iLike]: `%${searchQuery}%`,
+  },
+}
+
+// Numeric columns: cast to varchar then ILIKE
+Sequelize.where(
+  Sequelize.cast(Sequelize.col(`${tableName}.${attribute}`), 'varchar'),
+  { [Op.iLike]: `%${searchQuery}%` },
+)
+```
+
+### Match Detection
+
+After finding records, the service identifies which attributes matched:
+
+```javascript
+const matchAttribute = [];
+
+// Check text columns
+for (const attribute of attributesToSearch) {
+  if (record[attribute]?.toLowerCase()?.includes(normalizedSearchQuery)) {
+    matchAttribute.push(attribute);
+  }
+}
+
+// Check numeric columns (cast to string)
+for (const attribute of attributesIntToSearch) {
+  const castedValue = String(record[attribute]);
+  if (castedValue && castedValue.toLowerCase().includes(normalizedSearchQuery)) {
+    matchAttribute.push(attribute);
+  }
+}
+```
+
+## Middleware Chain
+
+### Route Configuration
+
+```typescript
+// backend/src/routes/search.ts
+import { checkCrudPermissions } from '../middlewares/check-permissions.ts';
+router.use(checkCrudPermissions('search'));
+
+router.post('/', async (req, res) => {
+  const foundMatches = await SearchService.search(searchQuery, req.currentUser);
+  res.json(foundMatches);
+});
+```
+
+### Middleware Flow
+
+```
+Request → JWT Auth → checkCrudPermissions('search') → SearchService.search()
+                              │
+                              ▼
+                     Checks READ_SEARCH permission
+                     using currentUser.app_role
+```
+
+## Role Requirements
+
+### Minimum Permissions for Search
+
+| Permission | Required For |
+|------------|--------------|
+| `READ_SEARCH` | Access to search endpoint |
+| `READ_<TABLE>` | See results from specific table |
+
+### Example Role Configuration
+
+```javascript
+// Role: "ContentEditor" with search access to projects and pages
+{
+  name: "ContentEditor",
+  permissions: [
+    "READ_SEARCH",
+    "READ_PROJECTS",
+    "READ_TOUR_PAGES",
+    "READ_PAGE_ELEMENTS",
+    "READ_ASSETS"
+  ]
+}
+```
+
+## Performance Characteristics
+
+### Parallel Execution
+
+All table searches execute in parallel using `Promise.all`:
+
+```javascript
+const searchTasks = Object.keys(tableColumns).map(async (tableName) => {
+  // Each table search runs concurrently
+});
+const resultsByTable = await Promise.all(searchTasks);
+return resultsByTable.flat();
+```
+
+### Limits
+
+| Limit | Value | Description |
+|-------|-------|-------------|
+| Results per table | 50 | Maximum records returned from each table |
+| Total tables | 10 | Number of searchable tables |
+| Max total results | 500 | Theoretical maximum (50 × 10 tables) |
+
+## File Structure
+
+```
+backend/src/
+├── routes/
+│   └── search.ts                    # Search route with permission check
+├── services/
+│   └── search.ts                    # SearchService with table definitions
+└── middlewares/
+    └── check-permissions.ts         # Permission checking middleware
+
+frontend/src/
+├── components/
+│   ├── Search.tsx                   # Global search input in navbar
+│   └── SearchResults.tsx            # Search results display component
+├── pages/
+│   └── search.tsx                   # Search results page
+└── layouts/
+    └── Authenticated.tsx            # Includes Search component in navbar
+```
+
+## Frontend Integration
+
+### Global Search Input
+
+**Source:** `frontend/src/components/Search.tsx`
+
+The navbar includes a global search input that:
+- Validates minimum 2 characters
+- Redirects to `/search?query=<searchQuery>`
+
+```tsx
+<Formik
+  onSubmit={(values) => {
+    router.push(`/search?query=${values.search}`);
+  }}
+>
+  <Field name='search' placeholder='Search' validate={validateSearch} />
+</Formik>
+```
+
+### Search Results Page
+
+**Source:** `frontend/src/pages/search.tsx`
+
+**URL:** `/search?query=<searchQuery>`
+
+**Permission:** `CREATE_SEARCH` (via LayoutAuthenticated wrapper)
+
+> **Note:** The page uses `CREATE_SEARCH` permission while the API requires `READ_SEARCH`.
+
+The search results page:
+- Extracts query from URL parameters
+- Calls `POST /search` with searchQuery
+- Groups results by tableName
+- Displays results using SearchResults component
+
+### Search Results Component
+
+**Source:** `frontend/src/components/SearchResults.tsx`
+
+Displays search results grouped by table:
+- Shows table name as section header (humanized)
+- Renders results in a table with all searchable columns
+- Clickable rows navigate to `/<tableName>/<tableName>-view/?id=<id>`
+
+```tsx
+// Results grouped by table
+{Object.keys(searchResults).map((tableName) => (
+  <CardBox>
+    <table>
+      {/* Headers from result keys */}
+      {/* Clickable rows linking to entity view */}
+    </table>
+  </CardBox>
+))}
+```
+
+## Known Considerations
+
+1. **No Pagination:** The search returns all results up to the per-table limit. For large result sets, consider implementing pagination.
+
+2. **JSON Column Search:** Searching JSON columns (ui_schema_json, manifest_json, asset_list_json) searches the raw JSON text, not parsed values.
+
+3. **Permission Inconsistency:** The search results page uses `CREATE_SEARCH` permission wrapper, but the API endpoint checks `READ_SEARCH`. Users need both permissions to use frontend search.
+
+4. **Numeric Search:** Numbers are cast to strings for matching. Searching "10" will match "100", "210", etc.
+
+5. **Permission Caching:** User permissions are fetched fresh for each search request. No caching is implemented at the service level.
+
+6. **No Role Error:** If user has no app_role, the service throws `ValidationError('auth.forbidden')` - there is no fallback to a public role.
+
+7. **Search Query Required:** Empty or missing search queries return a 400 error, not empty results.
+
+8. **Minimum Query Length:** Frontend validates minimum 2 characters, but API accepts any non-empty string.
+
+9. **Excluded Tables:** The following tables are intentionally not included in global search:
+   - `permissions` - System configuration, not user content
+   - `roles` - System configuration, not user content
+   - `project_memberships` - Access control data, not searchable content
+   - `element_type_defaults` - System configuration for default element settings
+   - `project_element_defaults` - Project-specific element settings (managed separately)
+
+## Usage Examples
+
+### cURL Example
+
+```bash
+curl -X POST http://localhost:3000/api/search \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <jwt-token>" \
+  -d '{"searchQuery": "vacation"}'
+```
+
+### JavaScript Example
+
+```javascript
+const response = await fetch('/api/search', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${token}`,
+  },
+  body: JSON.stringify({ searchQuery: 'vacation' }),
+});
+
+const results = await response.json();
+
+// Group results by table
+const byTable = results.reduce((acc, result) => {
+  if (!acc[result.tableName]) acc[result.tableName] = [];
+  acc[result.tableName].push(result);
+  return acc;
+}, {});
+```
diff --git a/documentation/ui-elements.md b/documentation/ui-elements.md
new file mode 100644
index 0000000..169859d
--- /dev/null
+++ b/documentation/ui-elements.md
@@ -0,0 +1,2748 @@
+# UI Elements
+
+Complete documentation for the Tour Builder Platform's UI Elements system including configuration, settings, and the three-tier scope hierarchy.
+
+## Overview
+
+The platform implements a three-tier UI Elements defaults hierarchy:
+1. **Global Scope (element_type_defaults)** - Platform-wide default configurations for element types
+2. **Project Scope (project_element_defaults)** - Project-specific settings snapshots/overrides
+3. **Instance Scope (tour_pages.ui_schema_json)** - Page-specific element instances with custom settings
+
+**Note:** Page-specific element instances are stored directly in `tour_pages.ui_schema_json`, not in a separate table.
+
+**Write contract:** `tour_pages` create/update requests validate `ui_schema_json`
+as a top-level JSON object. Valid object payloads must either contain
+`elements` as an array or omit it; omitted `elements` is normalized to
+`elements: []` before saving. JSON strings are accepted for legacy callers,
+parsed by the backend service, and rejected if the parsed value is not an
+object or if `elements` is not an array. The project does not currently use a
+schema/version field, derived metadata tables, or normalized page-element
+tables; asset usage and preload discovery continue to use existing extraction
+helpers.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      UI Elements Architecture                            │
+│                                                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │              Global Scope (element_type_defaults)                 │  │
+│  │              System-wide default configurations                   │  │
+│  │                                                                   │  │
+│  │   12 predefined element types with default settings:              │  │
+│  │   • navigation_next  • navigation_prev  • spot      • description │  │
+│  │   • gallery  • carousel  • logo  • video_player                   │  │
+│  │   • audio_player  • popup  • info_panel                           │  │
+│  └───────────────────────────┬──────────────────────────────────────┘  │
+│                              │                                          │
+│                    (auto-snapshot on project creation)                  │
+│                              │                                          │
+│                              ▼                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │            Project Scope (project_element_defaults)               │  │
+│  │              Project-specific overrides                           │  │
+│  │                                                                   │  │
+│  │   • Auto-snapshotted from global defaults on project creation     │  │
+│  │   • Can be customized per project                                 │  │
+│  │   • "Reset to Global" restores original values                    │  │
+│  │   • Tracks source_element_id for "Check for Updates"              │  │
+│  └───────────────────────────┬──────────────────────────────────────┘  │
+│                              │                                          │
+│                    (applies defaults to new elements)                   │
+│                              │                                          │
+│                              ▼                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │           Page Elements (tour_pages.ui_schema_json)               │  │
+│  │              Page-specific element instances                      │  │
+│  │                                                                   │  │
+│  │   • Stored inline in tour_pages.ui_schema_json.elements[]        │  │
+│  │   • Unlimited instances per page                                  │  │
+│  │   • Custom position, styling, content                             │  │
+│  │   • Navigation uses targetPageSlug (not IDs)                      │  │
+│  └──────────────────────────────────────────────────────────────────┘  │
+│                              │                                          │
+│              ┌───────────────┴───────────────┐                         │
+│              ▼                               ▼                         │
+│     ┌────────────────┐              ┌────────────────┐                 │
+│     │  Constructor   │              │    Runtime     │                 │
+│     │  (Edit mode)   │              │  (Playback)    │                 │
+│     └────────────────┘              └────────────────┘                 │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Global Scope (element_type_defaults)
+
+### Database Model
+
+**File:** `backend/src/db/models/element_type_defaults.js`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| id | UUID | Yes | UUIDv4 | Primary key |
+| element_type | TEXT | Yes | - | Unique identifier (e.g., 'navigation_next') |
+| name | TEXT | Yes | - | Human-readable name (1-255 chars) |
+| sort_order | INTEGER | Yes | 0 | Display order in admin UI |
+| is_active | VIRTUAL | - | true | Always returns true (convenience field) |
+| default_settings_json | TEXT | No | null | JSON-serialized default configuration |
+| importHash | VARCHAR(255) | No | null | Unique hash for imports |
+| createdAt | TIMESTAMP | Yes | Auto | Creation timestamp |
+| updatedAt | TIMESTAMP | Yes | Auto | Update timestamp |
+| deletedAt | TIMESTAMP | No | null | Soft delete timestamp |
+
+**Note:** The `default_settings_json` field is stored as `settings_json` in the database (field alias).
+
+**Indexes:**
+- `element_type` - Unique constraint (via column definition, creates implicit unique index)
+- `element_type` - Additional non-unique index (explicitly defined)
+- `sort_order` - For ordered queries
+- `deletedAt` - Soft delete queries
+
+**Relationships:**
+```
+element_type_defaults
+├── hasMany project_element_defaults (as snapshots) ─── SET NULL on delete
+├── belongsTo users (as createdBy) ─── Audit trail
+└── belongsTo users (as updatedBy) ─── Audit trail
+```
+
+### Predefined Element Types
+
+**File:** `backend/src/db/api/element_type_defaults.ts`
+
+The system auto-seeds 12 default element types on first database access via `DEFAULT_ROWS`:
+
+| Element Type | Name | Sort Order | Purpose |
+|--------------|------|------------|---------|
+| navigation_next | Navigation Forward Button | 1 | Forward navigation |
+| navigation_prev | Navigation Back Button | 2 | Back navigation |
+| tooltip | Tooltip | 3 | Hover information |
+| description | Description | 4 | Text content block |
+| gallery | Gallery | 5 | Image gallery cards |
+| carousel | Carousel | 6 | Image slideshow |
+| video_player | Video Player | 7 | Embedded video |
+| audio_player | Audio Player | 8 | Embedded audio |
+| spot | Hotspot | 9 | Interactive clickable area |
+| logo | Logo | 10 | Brand logo display |
+| popup | Popup | 11 | Modal dialog |
+| info_panel | Info Panel | 12 | Interactive panel with images/embeds |
+
+### Default Settings by Type
+
+#### Navigation (navigation_next, navigation_prev)
+
+```javascript
+{
+  label: 'Navigation: Forward',  // or 'Navigation: Back'
+  navLabel: 'Forward',           // or 'Back'
+  navLabelFontFamily: '',        // Font key for label text (e.g., 'instrument-sans-condensed')
+  navType: 'forward',            // 'forward' | 'back'
+  navDisabled: false,
+  transitionReverseMode: 'auto_reverse',  // 'auto_reverse' | 'separate_video'
+  transitionDurationSec: 0.7,
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+#### Tooltip (Deprecated)
+
+> **Note:** The Tooltip element type has been deprecated and removed from the frontend constructor. The backend defaults remain for backward compatibility with existing projects.
+
+```javascript
+{
+  label: 'Tooltip',
+  tooltipTitle: 'Tooltip title',
+  tooltipText: 'Tooltip text',
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+#### Description
+
+```javascript
+{
+  label: 'Description',
+  descriptionTitle: 'TITLE',
+  descriptionText: '',
+  descriptionTitleFontSize: '48px',
+  descriptionTextFontSize: '36px',
+  descriptionTitleFontFamily: 'inherit',
+  descriptionTextFontFamily: 'inherit',
+  descriptionTitleColor: '#000000',
+  descriptionTextColor: '#4B5563',
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+**Note:** Background color is controlled via the CSS Styles tab (`backgroundColor` property) rather than a separate description-specific field.
+
+#### Gallery
+
+```javascript
+{
+  label: 'Gallery',
+  galleryCards: [
+    { imageUrl: '', title: 'Card 1', description: '' }
+  ],
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+#### Carousel
+
+```javascript
+{
+  label: 'Carousel',
+  carouselSlides: [
+    { imageUrl: '', caption: 'Slide 1' }
+  ],
+  carouselPrevIconUrl: '',
+  carouselNextIconUrl: '',
+  carouselCaptionFontFamily: '',
+  carouselFullWidth: false,
+  // Button positions (percentage 0-100, for full-width mode)
+  carouselPrevX: 5,
+  carouselPrevY: 50,
+  carouselNextX: 95,
+  carouselNextY: 50,
+  // Button dimensions (CSS values, for navigation-style rendering)
+  carouselPrevWidth: '',
+  carouselPrevHeight: '',
+  carouselNextWidth: '',
+  carouselNextHeight: '',
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+#### Video Player
+
+```javascript
+{
+  label: 'Video Player',
+  mediaUrl: '',
+  mediaAutoplay: true,
+  mediaLoop: true,
+  mediaMuted: true,
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+#### Audio Player
+
+```javascript
+{
+  label: 'Audio Player',
+  mediaUrl: '',
+  mediaAutoplay: true,
+  mediaLoop: true,
+  mediaMuted: false,  // Note: Audio is NOT muted by default
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+#### Spot (Hotspot)
+
+```javascript
+{
+  label: 'Hotspot',
+  iconUrl: '',
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+#### Logo
+
+```javascript
+{
+  label: 'Logo',
+  iconUrl: '',
+  backgroundImageUrl: '',
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+#### Popup
+
+```javascript
+{
+  label: 'Popup',
+  iconUrl: '',
+  popupTitle: '',
+  popupContent: '',
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+#### Info Panel
+
+```javascript
+{
+  label: 'Info Panel',
+  // Trigger position (width/height intentionally not set - trigger sizes based on content)
+  // Users can explicitly set width/height if fixed dimensions are needed
+  xPercent: 5,
+  yPercent: 90,
+  infoPanelTriggerFontFamily: '',
+  infoPanelDisabled: false,
+  infoPanelOpenByDefault: false,
+  // Hover reveal (disabled by default)
+  hoverReveal: false,
+  hoverRevealInitialOpacity: '1',
+  hoverRevealTargetOpacity: '1',
+  hoverRevealDuration: '0.3s',
+  // Header section
+  infoPanelHeaderImageUrl: '',
+  infoPanelHeaderText: '',
+  infoPanelHeaderBackgroundColor: '',
+  infoPanelHeaderColor: '#ffffff',
+  infoPanelHeaderFontFamily: '',
+  infoPanelHeaderFontSize: '24',
+  infoPanelHeaderFontWeight: '700',
+  infoPanelHeaderPadding: '8',
+  infoPanelHeaderBorderRadius: '8',
+  infoPanelHeaderTextAlign: 'center',
+  infoPanelHeaderMinHeight: '',
+  // Panel content
+  panelTitle: 'Information',
+  panelText: '',
+  // Layout
+  infoPanelSectionGap: '12',
+  // Panel position & wrapper styling
+  panelXPercent: 30,
+  panelYPercent: 50,
+  panelWidth: '400',
+  panelHeight: 'auto',
+  panelBackgroundColor: 'rgba(0, 0, 0, 0.85)',
+  panelBorderRadius: '12',
+  panelPadding: '20',
+  panelBackdropBlur: '10px',
+  panelOverlayColor: 'rgba(0, 0, 0, 0.3)',
+  panelBorderWidth: '0',
+  panelBorderColor: '#ffffff',
+  panelBorderStyle: 'solid',
+  // Title section styles
+  panelTitleColor: '#ffffff',
+  panelTitleFontSize: '18',
+  panelTitleFontFamily: '',
+  infoPanelTitleBackgroundColor: '',
+  infoPanelTitlePadding: '4 8',
+  infoPanelTitleFontWeight: '600',
+  infoPanelTitleTextAlign: 'left',
+  // Text section styles
+  panelTextColor: '#cccccc',
+  panelTextFontSize: '14',
+  panelTextFontFamily: '',
+  // Span section styles
+  infoPanelSpanBackgroundColor: 'rgba(255, 255, 255, 0.1)',
+  infoPanelSpanColor: '#ffffff',
+  infoPanelSpanFontFamily: '',
+  infoPanelSpanFontSize: '12',
+  infoPanelSpanPadding: '4 8',
+  infoPanelSpanBorderRadius: '6',
+  infoPanelSpanGap: '8',
+  // Card section styles
+  infoPanelCardBackgroundColor: 'rgba(0, 0, 0, 0.3)',
+  infoPanelCardBorderRadius: '8',
+  infoPanelCardAspectRatio: '16/9',
+  infoPanelCardMinHeight: '',
+  infoPanelCardGap: '8',
+  // Card title overlay styles
+  infoPanelCardTitleBackgroundColor: 'rgba(0, 0, 0, 0.6)',
+  infoPanelCardTitleColor: '#ffffff',
+  infoPanelCardTitleFontFamily: '',
+  infoPanelCardTitleFontSize: '12',
+  infoPanelCardTitlePadding: '4 8',
+  // Detail panel
+  detailXPercent: 70,
+  detailYPercent: 50,
+  detailWidth: '500',
+  detailHeight: '400',
+  detailBackgroundColor: 'rgba(0, 0, 0, 0.9)',
+  detailBorderRadius: '12',
+  detailPadding: '12',
+  detailCaptionFontFamily: '',
+  detailBorderWidth: '0',
+  detailBorderColor: '#ffffff',
+  detailBorderStyle: 'solid',
+  // Section instances with per-section data/settings
+  infoPanelSections: [
+    { id: 'default-header', type: 'header' },
+    { id: 'default-title', type: 'title' },
+    { id: 'default-text', type: 'text' },
+    { id: 'default-spans', type: 'spans', columns: 3, gap: '8', spans: [] },
+    { id: 'default-images', type: 'images', images: [] },
+  ],
+  // Media section settings
+  infoPanelImagesPreviewHeight: '300',
+  infoPanelImagesThumbnailSize: '80',
+  appearDelaySec: 0,
+  appearDurationSec: null
+}
+```
+
+### Auto-Initialization
+
+**File:** `backend/src/db/api/element_type_defaults.ts`
+
+The `ensureInitialized()` method guarantees defaults exist:
+
+```javascript
+static async ensureInitialized() {
+  // Singleton pattern with promise caching
+  if (!this.initializationPromise) {
+    this.initializationPromise = (async () => {
+      let count = await this.MODEL.count();
+
+      // Handle table not existing (code 42P01)
+      // Sync table if needed
+
+      if (count > 0) return;  // Already initialized
+
+      // Seed DEFAULT_ROWS
+      await this.MODEL.bulkCreate(
+        this.DEFAULT_ROWS.map(item => ({
+          ...this.getFieldMapping(item),
+          createdAt: new Date(),
+          updatedAt: new Date()
+        }))
+      );
+    })();
+  }
+  await this.initializationPromise;
+}
+```
+
+Every API method calls `ensureInitialized()` first, making the seeding idempotent.
+
+## Project Scope (project_element_defaults)
+
+### Database Model
+
+**File:** `backend/src/db/models/project_element_defaults.js`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| id | UUID | Yes | UUIDv4 | Primary key |
+| projectId | UUID (FK) | Yes | - | Reference to projects |
+| element_type | TEXT | Yes | - | Element type identifier |
+| name | TEXT | No | null | Custom display name |
+| sort_order | INTEGER | Yes | 0 | Display order |
+| settings_json | TEXT | No | null | JSON-serialized settings |
+| source_element_id | UUID (FK) | No | null | Reference to global default (for tracking) |
+| snapshot_version | INTEGER | Yes | 1 | Version for update tracking |
+| importHash | VARCHAR(255) | No | null | Unique import hash |
+| createdAt | TIMESTAMP | Yes | Auto | Creation timestamp |
+| updatedAt | TIMESTAMP | Yes | Auto | Update timestamp |
+| deletedAt | TIMESTAMP | No | null | Soft delete timestamp |
+
+**Unique Constraint:** `(projectId, element_type)` - One override per type per project
+
+**Indexes:**
+- `projectId` - FK lookup
+- `projectId, element_type` - Unique composite
+- `element_type` - Type filtering
+- `source_element_id` - Global default tracking
+- `deletedAt` - Soft delete queries
+
+**Relationships:**
+```
+project_element_defaults
+├── belongsTo projects (as project) ─── CASCADE on delete
+├── belongsTo element_type_defaults (as source_element) ─── SET NULL on delete
+├── belongsTo users (as createdBy) ─── Audit trail
+└── belongsTo users (as updatedBy) ─── Audit trail
+```
+
+### Auto-Snapshot on Project Creation
+
+When a new project is created, all global element defaults are automatically copied to the project:
+
+**File:** `backend/src/db/api/projects.ts`
+
+```javascript
+static async create(options) {
+  const project = await super.create(options);
+
+  // Auto-snapshot global element defaults to project
+  try {
+    const Project_element_defaultsDBApi = require('./project_element_defaults.ts').default;
+    await Project_element_defaultsDBApi.snapshotGlobalDefaults(project.id, options);
+  } catch (error) {
+    console.error('Failed to snapshot global element defaults:', error);
+    // Non-fatal - project is still created
+  }
+
+  return project;
+}
+```
+
+**File:** `backend/src/db/api/project_element_defaults.ts`
+
+```javascript
+static async snapshotGlobalDefaults(projectId, options = {}) {
+  const globalDefaults = await Element_type_defaultsDBApi.findAll({});
+
+  const projectDefaults = await this.MODEL.bulkCreate(
+    globalDefaults.rows.map((globalDefault) => ({
+      projectId,
+      element_type: globalDefault.element_type,
+      name: globalDefault.name,
+      sort_order: globalDefault.sort_order,
+      settings_json: globalDefault.default_settings_json,
+      source_element_id: globalDefault.id,  // Track source for updates
+      snapshot_version: 1,
+      createdById: options.currentUser?.id,
+      updatedById: options.currentUser?.id,
+    })),
+    { transaction: options.transaction }
+  );
+
+  return projectDefaults;
+}
+```
+
+### Reset and Diff Operations
+
+**Reset to Global:** Restore a project's element default to the current global value
+
+```javascript
+static async resetToGlobalDefault(projectId, element_type, options = {}) {
+  // Find the global default
+  const globalDefault = await Element_type_defaultsDBApi.findByType(element_type);
+  if (!globalDefault) throw new ValidationError('Global default not found');
+
+  // Update project default
+  return this.update(
+    projectDefault.id,
+    {
+      settings_json: globalDefault.default_settings_json,
+      source_element_id: globalDefault.id,
+      snapshot_version: projectDefault.snapshot_version + 1,
+    },
+    options
+  );
+}
+```
+
+**Diff from Global:** Check if project settings differ from current global
+
+```javascript
+static async diffFromGlobal(projectId, element_type) {
+  const projectDefault = await this.findByProjectAndType(projectId, element_type);
+  const globalDefault = await Element_type_defaultsDBApi.findByType(element_type);
+
+  const isDifferent = JSON.stringify(projectDefault?.settings_json) !==
+                      JSON.stringify(globalDefault?.default_settings_json);
+
+  return {
+    isDifferent,
+    hasGlobalDefault: !!globalDefault,
+    projectDefault,
+    globalDefault,
+  };
+}
+```
+
+## Page Elements (Inline Storage)
+
+### Data Structure
+
+Page elements are stored directly in `tour_pages.ui_schema_json.elements[]`, not in a separate table. This simplifies the data model and eliminates ID remapping during publishing.
+
+**Storage Location:** `tour_pages.ui_schema_json`
+
+Constructor copy/paste is handled within this inline element array. Copy stores
+the selected element in a constructor-local clipboard, and Paste appends a deep
+clone to the active page. All settings are preserved, including position,
+dimensions, CSS styles, effects, media URLs, links, navigation `targetPageSlug`,
+and transition fields. The pasted element receives fresh instance IDs for the
+element itself and nested gallery, carousel, and info-panel items so the clone is
+independent from the source.
+
+```typescript
+interface UISchemaJSON {
+  elements: UIElement[];
+}
+
+interface UIElement {
+  id: string;              // Generated UUID for this element
+  type: string;            // Element type (navigation_next, spot, etc.)
+  name?: string;           // Instance name
+  sortOrder: number;       // Z-order on page
+  isVisible: boolean;      // Visibility toggle
+  xPercent?: number;       // X position (0-100%)
+  yPercent?: number;       // Y position (0-100%)
+  widthPercent?: number;   // Width as percentage
+  heightPercent?: number;  // Height as percentage
+  rotationDeg?: number;    // Rotation in degrees
+  // ... additional type-specific fields (iconUrl, targetPageSlug, etc.)
+}
+```
+
+**Standard Element Types:**
+
+```javascript
+const ELEMENT_TYPES = [
+  'navigation_next',  // Forward navigation
+  'navigation_prev',  // Back navigation
+  'spot',             // Hotspot/clickable area
+  'description',      // Text description
+  'gallery',          // Image gallery
+  'carousel',         // Image carousel
+  'logo',             // Logo element
+  'video_player',     // Video player
+  'audio_player',     // Audio player
+  'popup',            // Modal popup
+  'info_panel',       // Info panel with images/embeds
+];
+```
+
+**Benefits of Inline Storage:**
+- No separate table to manage
+- Elements copied automatically with pages during publishing
+- Navigation uses `targetPageSlug` (consistent across environments)
+- No ID remapping needed
+
+### Style JSON Structure
+
+The `style_json` field stores CSS properties:
+
+```typescript
+interface StyleJson {
+  width?: string;           // e.g., '24vw'
+  height?: string;          // e.g., '8vh'
+  minWidth?: string;
+  maxWidth?: string;
+  minHeight?: string;
+  maxHeight?: string;
+  margin?: string;          // e.g., '0 auto'
+  padding?: string;         // e.g., '0.5rem 0.75rem'
+  gap?: string;
+  fontSize?: string;        // e.g., '0.875rem'
+  lineHeight?: string;
+  fontWeight?: string;      // e.g., '500'
+  border?: string;          // e.g., '2px solid currentColor'
+  borderRadius?: string;    // e.g., '8px'
+  opacity?: string;         // CSS opacity stored as 0..1, e.g., '0', '0.5', '0.95', '1'
+  boxShadow?: string;       // e.g., '0 4px 12px rgba(0,0,0,0.1)'
+  display?: string;         // 'block' | 'flex' | 'grid' | etc.
+  position?: string;        // 'static' | 'relative' | 'absolute' | etc.
+  justifyContent?: string;  // 'flex-start' | 'center' | etc.
+  alignItems?: string;      // 'stretch' | 'center' | etc.
+  textAlign?: string;       // 'left' | 'center' | 'right'
+  zIndex?: string;          // e.g., '10'
+}
+```
+
+Constructor/defaults editors display opacity as a clamped percentage from 0 to
+100 and convert it back to CSS opacity from 0 to 1 before saving.
+Opacity belongs to the shared style defaults list, so values configured in
+`element_type_defaults.default_settings_json` or
+`project_element_defaults.settings_json` are applied when new page elements are
+created unless the page element overrides opacity locally.
+
+Element `zIndex` values are normalized to numbers and applied to the outer
+absolutely-positioned wrapper used by constructor and runtime rendering. This
+lets overlapping page elements stack by CSS panel value instead of only by
+creation/render order.
+
+### CSS Unit Normalization (Canvas Units)
+
+Style values are automatically normalized to **Canvas Units (--cu)** for responsive scaling across all viewport sizes. The `--cu` CSS custom property represents "1 design pixel" and scales proportionally with the viewport.
+
+> **See:** [UI Adaptivity System](../frontend/docs/ui-adaptivity-system.md) for complete documentation.
+
+**Canvas Unit Scaling:**
+```
+At design resolution (1920×1080 on 1920×1080 viewport): --cu = 1px
+At 4K (3840×2160 viewport): --cu = 2px (elements render 2x larger)
+At half-resolution (960×540 viewport): --cu = 0.5px (elements render at half size)
+```
+
+**General Element Styles (via `elementStyles.ts`):**
+
+| Property | Conversion | Example |
+|----------|------------|---------|
+| width, minWidth, maxWidth | Canvas units | `"200"` → `"calc(200 * var(--cu, 1px))"` |
+| height, minHeight, maxHeight | Canvas units | `"100"` → `"calc(100 * var(--cu, 1px))"` |
+| borderRadius | Canvas units | `"12"` → `"calc(12 * var(--cu, 1px))"` |
+| fontSize | Canvas units | `"16"` → `"calc(16 * var(--cu, 1px))"` |
+| border | none | Complex value, preserved as-is |
+
+**Legacy Unit Conversion:**
+| Input | Output |
+|-------|--------|
+| `"24px"` | `"calc(24 * var(--cu, 1px))"` |
+| `"50vw"` | `"calc(960 * var(--cu, 1px))"` (50% of 1920) |
+| `"25vh"` | `"calc(270 * var(--cu, 1px))"` (25% of 1080) |
+| `"1.5rem"` | `"calc(24 * var(--cu, 1px))"` (1.5 × 16) |
+
+**Edge Cases Handled:**
+- Values already using `var(--cu)` → preserved
+- Complex values with spaces (e.g., `"10px 20px"`) → preserved
+- CSS functions (e.g., `"calc(100% - 20px)"`) → preserved
+- CSS variables (e.g., `"var(--spacing)"`) → preserved
+- Zero values → `"0"` (no unit needed)
+- Negative values → converted (e.g., `"-10"` → `"calc(-10 * var(--cu, 1px))"`)
+
+**JavaScript Usage:**
+```typescript
+import { toCU } from '../lib/canvasScale';
+
+const style = {
+  fontSize: toCU(16),       // "calc(16 * var(--cu, 1px))"
+  padding: toCU(12),        // "calc(12 * var(--cu, 1px))"
+  borderRadius: toCU(8),    // "calc(8 * var(--cu, 1px))"
+};
+```
+
+### CSS Inheritance
+
+Inheritable CSS properties (color, fontSize, fontWeight, lineHeight) cascade from parent elements to children via CSS inheritance. This enables setting styles once on the wrapper and having them apply to all child sections.
+
+**Wrapper → Child Inheritance:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Element Wrapper (General Element Styles)                          │
+│ • color: #ffffff                                                 │
+│ • fontSize: 1rem                                                 │
+│ • fontWeight: 500                                                │
+│ • lineHeight: 1.5                                                │
+├─────────────────────────────────────────────────────────────────┤
+│ Child Section (e.g., Gallery Header)                             │
+│ • If galleryHeaderColor is NOT set → inherits #ffffff            │
+│ • If galleryHeaderColor IS set → uses explicit value             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Implementation Pattern:**
+
+```typescript
+// applyIfSet - only applies value if explicitly set (allows CSS inheritance)
+applyIfSet(style, 'color', element.galleryHeaderColor);
+applyIfSet(style, 'fontSize', element.galleryHeaderFontSize, normalizeRemValue);
+
+// applyWithDefault - applies value or falls back to default (blocks inheritance)
+applyWithDefault(style, 'padding', element.galleryHeaderPadding, defaults.padding);
+```
+
+**Elements Supporting Inheritance:**
+| Element | Inheritable From Wrapper |
+|---------|--------------------------|
+| NavigationElement | color, fontSize, fontWeight |
+| PopupElement | color, fontSize, fontWeight |
+| DescriptionElement | color, fontSize, fontWeight (title & text sections) |
+| GalleryElement | color, fontSize, fontWeight (all sections: header, title, spans, cards) |
+| InfoPanelElement | color, fontSize, fontWeight (all sections: header, title, text, spans, cards) |
+
+### Content JSON Structure
+
+The `content_json` field stores type-specific content:
+
+**Navigation:**
+```typescript
+{
+  iconUrl?: string;
+  navLabel?: string;
+  navLabelFontFamily?: string;  // Font key for label text
+  navType?: 'forward' | 'back';
+  navDisabled?: boolean;
+  targetPageSlug?: string;  // Slug-based navigation (consistent across environments)
+  transitionVideoUrl?: string;
+  transitionReverseMode?: 'auto_reverse' | 'separate_video';
+  reverseVideoUrl?: string;
+  transitionDurationSec?: number;
+}
+```
+
+**Tooltip:**
+```typescript
+{
+  iconUrl?: string;
+  tooltipTitle?: string;
+  tooltipText?: string;
+  tooltipTitleFontFamily?: string;
+  tooltipTextFontFamily?: string;
+}
+```
+
+**Description:**
+```typescript
+{
+  descriptionTitle?: string;
+  descriptionText?: string;
+  descriptionTitleFontSize?: string;
+  descriptionTextFontSize?: string;
+  descriptionTitleFontFamily?: string;
+  descriptionTextFontFamily?: string;
+  descriptionTitleColor?: string;
+  descriptionTextColor?: string;
+  // Background color is controlled via CSS Styles tab (backgroundColor property)
+}
+```
+
+**Gallery:**
+```typescript
+{
+  galleryCards?: Array<{
+    id: string;
+    imageUrl: string;
+    title: string;
+    description: string;
+  }>;
+  galleryHeaderImageUrl?: string;
+  galleryTitle?: string;
+  galleryInfoSpans?: Array<{
+    id: string;
+    text: string;
+  }>;
+  galleryColumns?: number;
+  galleryTitleFontFamily?: string;
+  galleryTextFontFamily?: string;  // Font for card titles, descriptions, and info spans
+  // Gallery header dimension properties
+  galleryHeaderWidth?: string;      // e.g., "100%", "80%", "300px"
+  galleryHeaderHeight?: string;     // e.g., "200px", "20vh", "auto"
+  galleryHeaderMinHeight?: string;  // e.g., "150px"
+  galleryHeaderMaxHeight?: string;  // e.g., "400px", "50vh"
+  // Gallery card dimension properties
+  galleryCardWidth?: string;        // e.g., "auto", "100%", "250px"
+  galleryCardHeight?: string;       // e.g., "auto", "200px"
+  galleryCardMinHeight?: string;    // e.g., "150px" (default: "40px")
+  galleryCardAspectRatio?: string;  // e.g., "4/3", "1/1", "16/9", "auto" (default: "4/3")
+  // Gallery carousel navigation icons/positions
+  galleryCarouselPrevIconUrl?: string;
+  galleryCarouselNextIconUrl?: string;
+  galleryCarouselBackIconUrl?: string;
+  galleryCarouselBackLabel?: string;
+  galleryCarouselPrevX?: number;
+  galleryCarouselPrevY?: number;
+  galleryCarouselNextX?: number;
+  galleryCarouselNextY?: number;
+  galleryCarouselBackX?: number;
+  galleryCarouselBackY?: number;
+  galleryCarouselPrevWidth?: string;
+  galleryCarouselPrevHeight?: string;
+  galleryCarouselNextWidth?: string;
+  galleryCarouselNextHeight?: string;
+  galleryCarouselBackWidth?: string;
+  galleryCarouselBackHeight?: string;
+  // Gallery section text alignment (default: 'center')
+  galleryHeaderTextAlign?: 'left' | 'center' | 'right';
+  galleryTitleTextAlign?: 'left' | 'center' | 'right';
+  gallerySpanTextAlign?: 'left' | 'center' | 'right';
+}
+```
+
+**Carousel:**
+```typescript
+{
+  carouselSlides?: Array<{
+    id: string;
+    imageUrl: string;
+    caption: string;
+  }>;
+  carouselPrevIconUrl?: string;
+  carouselNextIconUrl?: string;
+  carouselCaptionFontFamily?: string;
+  carouselFullWidth?: boolean;  // Full-width background mode
+  // Button positions (percentage 0-100, for full-width mode)
+  carouselPrevX?: number;
+  carouselPrevY?: number;
+  carouselNextX?: number;
+  carouselNextY?: number;
+  // Button dimensions (CSS values like '3vw', '5vh')
+  carouselPrevWidth?: string;
+  carouselPrevHeight?: string;
+  carouselNextWidth?: string;
+  carouselNextHeight?: string;
+}
+```
+
+**Media (Video/Audio):**
+```typescript
+{
+  mediaUrl?: string;
+  mediaAutoplay?: boolean;
+  mediaLoop?: boolean;
+  mediaMuted?: boolean;
+}
+```
+
+**Info Panel:**
+```typescript
+{
+  // Trigger button positioning and optional sizing
+  // xPercent, yPercent: position on canvas
+  // width, height: optional - if not set, trigger sizes based on content (icon or text)
+  // iconUrl: optional trigger icon
+  infoPanelTriggerLabel?: string;
+  infoPanelTriggerFontFamily?: string;
+  infoPanelDisabled?: boolean;
+  infoPanelOpenByDefault?: boolean;
+
+  // Panel content
+  panelTitle?: string;
+  panelText?: string;
+
+  // Header section
+  infoPanelHeaderImageUrl?: string;
+  infoPanelHeaderText?: string;
+
+  // Panel position & styling
+  panelXPercent?: number;        // 0-100
+  panelYPercent?: number;        // 0-100
+  panelWidth?: string;           // e.g., '400'
+  panelHeight?: string;          // e.g., 'auto'
+  panelBackgroundColor?: string; // e.g., 'rgba(0, 0, 0, 0.85)'
+  panelBorderRadius?: string;
+  panelPadding?: string;
+  panelBackdropBlur?: string;
+  panelOverlayColor?: string;    // Backdrop overlay
+  panelBorderWidth?: string;
+  panelBorderColor?: string;
+  panelBorderStyle?: 'none' | 'solid' | 'dashed' | 'dotted';
+  infoPanelSectionGap?: string;  // Gap between sections
+
+  // Section instances (NEW: allows multiple instances of same type)
+  infoPanelSections?: Array<{
+    id: string;                  // Unique section ID
+    type: 'header' | 'title' | 'text' | 'spans' | 'cards' | 'images';
+    columns?: number;            // Grid columns (spans, cards, images)
+    gap?: string;                // Gap between items
+    mediaOpenMode?: 'panel' | 'fullscreen';
+    spans?: InfoPanelInfoSpan[]; // For 'spans' sections
+    images?: InfoPanelImage[];   // For 'cards' or 'images' sections
+    text?: string;               // For 'text' sections
+    title?: string;              // For 'title' sections
+    headerImageUrl?: string;     // For 'header' sections
+    headerText?: string;         // For 'header' sections
+    clickAction?: 'target_page' | 'external_url';
+    targetPageSlug?: string;
+    externalUrl?: string;
+  }>;
+
+  // Media section settings
+  infoPanelSelectedImageId?: string;      // Restored as selected preview image when present
+  infoPanelImagesPreviewHeight?: string;
+  infoPanelImagesThumbnailSize?: string;
+
+  // Image Detail Panel
+  detailXPercent?: number;
+  detailYPercent?: number;
+  detailWidth?: string;
+  detailHeight?: string;
+  detailBackgroundColor?: string;
+  detailBorderRadius?: string;
+  detailPadding?: string;
+  detailCaptionFontFamily?: string;
+  detailBorderWidth?: string;
+  detailBorderColor?: string;
+  detailBorderStyle?: 'none' | 'solid' | 'dashed' | 'dotted';
+}
+```
+
+**Normalization:** Info Panel section instances are normalized when defaults are parsed/merged into canvas elements. Missing section IDs are regenerated, invalid section types fall back to `text`, and nested spans/images keep supported fields including `iconUrl` for 360 trigger buttons.
+
+**InfoPanelInfoSpan Structure:**
+```typescript
+{
+  id: string;
+  text: string;
+  iconUrl?: string;  // Renders icon instead of text when set
+  clickAction?: 'target_page' | 'external_url';
+  targetPageSlug?: string;
+  externalUrl?: string;
+}
+```
+
+**InfoPanelImage Structure:**
+```typescript
+{
+  id: string;
+  imageUrl?: string;            // Regular image URL (storage key)
+  videoUrl?: string;            // Video URL/storage key
+  embedUrl?: string;            // 360/3D embed URL (direct URL)
+  caption?: string;
+  itemType?: 'image' | 'video' | '360';
+  iconUrl?: string;             // Custom icon for 360° trigger
+  clickAction?: 'target_page' | 'external_url';
+  targetPageSlug?: string;
+  externalUrl?: string;
+}
+```
+
+## Element Types Reference
+
+### Navigation Buttons (navigation_next, navigation_prev)
+
+**Purpose:** Navigate between tour pages with optional video transitions.
+
+**Interactive Behavior:**
+- **Click:** Navigates to page matching `targetPageSlug` if set
+- **Disabled:** `navDisabled: true` suppresses navigation in constructor interact mode and runtime presentations; runtime hover/focus/active visuals are preserved
+- **Transition:** Plays `transitionVideoUrl` during navigation
+- **Reverse Mode:** Back navigation can reverse the transition video automatically (`auto_reverse`) or use a separate `reverseVideoUrl`
+
+**Runtime Rendering:**
+```tsx
+// With icon
+<Image src={element.iconUrl} alt="Navigation" fill className="object-contain" />
+
+// Without icon (text label)
+<div className="px-4 py-2 bg-white/80 rounded text-black text-sm">
+  {element.navLabel || (element.type === 'navigation_next' ? 'Next' : 'Back')}
+</div>
+```
+
+**Key Properties:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `iconUrl` | string | Custom button icon image |
+| `navLabel` | string | Text label (default: "Next"/"Back") |
+| `navLabelFontFamily` | string | Font key for label text (e.g., 'instrument-sans-condensed') |
+| `navType` | 'forward' \| 'back' | Direction for transition logic |
+| `navDisabled` | boolean | Disable navigation |
+| `targetPageSlug` | string | Destination page slug (consistent across environments) |
+| `transitionVideoUrl` | string | Video to play during transition |
+| `transitionReverseMode` | 'auto_reverse' \| 'separate_video' | Reverse playback mode |
+| `reverseVideoUrl` | string | Separate video for back navigation |
+| `transitionDurationSec` | number | Transition duration (default: 0.7) |
+
+### Hotspot (spot)
+
+**Purpose:** Interactive clickable area for triggering actions.
+
+**Interactive Behavior:**
+- **Click:** Triggers navigation or custom action
+- **Hover:** Can display tooltip or highlight (CSS-based)
+
+**Runtime Rendering:** Uses `iconUrl` or `imageUrl` if provided, otherwise transparent clickable area.
+
+### Description
+
+**Purpose:** Display formatted text content with title and body.
+
+**Interactive Behavior:**
+- **Static:** No default interactivity
+- **Click:** Can trigger navigation if `targetPageSlug` set
+
+**Runtime Rendering:**
+```tsx
+// With icon
+<Image src={element.iconUrl} alt="Description" fill className="object-contain" />
+
+// Without icon (text block)
+// Note: Background color is applied to the wrapper via CSS Styles (backgroundColor)
+<div className="p-4">
+  <p style={{ fontSize, fontFamily, color: titleColor }}>{descriptionTitle}</p>
+  <p style={{ fontSize, fontFamily, color: textColor }}>{descriptionText}</p>
+</div>
+```
+
+**Key Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `descriptionTitle` | string | "TITLE" | Title text |
+| `descriptionText` | string | "" | Body text |
+| `descriptionTitleFontSize` | string | "48px" | Title font size |
+| `descriptionTextFontSize` | string | "36px" | Body font size |
+| `descriptionTitleFontFamily` | string | "inherit" | Title font family |
+| `descriptionTextFontFamily` | string | "inherit" | Body font family |
+| `descriptionTitleColor` | string | "#000000" | Title color |
+| `descriptionTextColor` | string | "#4B5563" | Body color |
+
+**Note:** Background color is controlled via the CSS Styles tab (`backgroundColor` property) rather than a separate description-specific field.
+
+### Tooltip (Deprecated)
+
+> **Note:** The Tooltip element type has been deprecated and removed from the frontend constructor. Existing tooltip elements may still render in runtime, but new ones cannot be created. Backend defaults remain for backward compatibility.
+
+**Purpose:** Display contextual information on hover/click.
+
+**Interactive Behavior:**
+- **Hover/Click:** Typically shows expanded content (implementation-dependent)
+- **Display:** Compact card with title and text
+
+**Key Properties:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `iconUrl` | string | Trigger icon image |
+| `tooltipTitle` | string | Tooltip header text |
+| `tooltipText` | string | Tooltip body text |
+
+### Gallery
+
+**Purpose:** Display a grid of images with optional titles and descriptions.
+
+**Interactive Behavior:**
+- **Click on card:** Can open lightbox or navigate (implementation-dependent)
+- **Layout:** 3-column grid by default
+
+**Runtime Rendering:**
+```tsx
+<div className="grid grid-cols-3 gap-2 p-2 bg-black/50 rounded">
+  {galleryCards.map((card) => (
+    <div key={card.id} className="relative aspect-square">
+      <Image src={card.imageUrl} alt={card.title} fill className="object-cover rounded" />
+    </div>
+  ))}
+</div>
+```
+
+**Key Properties:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `galleryCards` | GalleryCard[] | Array of gallery items |
+
+**GalleryCard Structure:**
+```typescript
+{
+  id: string;
+  imageUrl: string;
+  title: string;
+  description: string;
+}
+```
+
+**Gallery Section Dimension Properties:**
+
+The CSS tab provides dimension controls for gallery sections:
+
+| Section | Property | Default | Description |
+|---------|----------|---------|-------------|
+| Header | `galleryHeaderWidth` | (none) | Header container width (e.g., "100%", "300px") |
+| Header | `galleryHeaderHeight` | `auto` | Header/image height |
+| Header | `galleryHeaderMinHeight` | (none) | Minimum header height |
+| Header | `galleryHeaderMaxHeight` | (none) | Maximum header height |
+| Cards | `galleryCardAspectRatio` | `4/3` | Card aspect ratio (4:3, 16:9, 1:1, 3:2, auto) |
+| Cards | `galleryCardMinHeight` | `40px` | Minimum card height |
+| Cards | `galleryCardWidth` | (none) | Card width (grid controls by default) |
+| Cards | `galleryCardHeight` | (none) | Card height (aspect ratio controls by default) |
+
+**Gallery Section Text Alignment:**
+
+Text alignment can be configured for each gallery section (header, title, spans):
+
+| Section | Property | Default | Values |
+|---------|----------|---------|--------|
+| Header | `galleryHeaderTextAlign` | `center` | `left`, `center`, `right` |
+| Title | `galleryTitleTextAlign` | `center` | `left`, `center`, `right` |
+| Info Spans | `gallerySpanTextAlign` | `center` | `left`, `center`, `right` |
+
+**Slide Transition Override Properties (Fullscreen Carousel Overlay):**
+
+When a gallery card is clicked, a fullscreen carousel overlay opens. These properties control slide transitions within that overlay:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `gallerySlideTransitionType` | `'fade' \| 'none' \| ''` | `''` | Transition type ('' = inherit from page transitions) |
+| `gallerySlideTransitionDurationMs` | `number \| ''` | `''` | Duration in ms ('' = inherit) |
+| `gallerySlideTransitionEasing` | `EasingFunction \| ''` | `''` | CSS easing function |
+| `gallerySlideTransitionOverlayColor` | `string` | `''` | Overlay color for fade ('' = inherit) |
+
+> **See:** [Project Transition Settings - Slide Transitions](project-transition-settings.md#slide-transitions-gallerycarousel) for cascade behavior.
+
+### Carousel
+
+**Purpose:** Image slideshow with navigation controls. Supports two modes:
+- **Normal mode:** Inline carousel within element dimensions
+- **Full-width mode:** Covers full viewport as background layer (z-10), other elements positioned above
+
+**Interactive Behavior:**
+- **Prev/Next buttons:** Navigate between slides (click)
+- **Arrow keys:** ArrowLeft/ArrowRight navigation (full-width mode, runtime only)
+- **Touch swipe:** Swipe left/right to navigate (full-width mode, runtime only)
+- **Draggable buttons:** Drag to reposition nav buttons (full-width mode, constructor only)
+
+**Runtime Rendering:**
+```tsx
+// Normal mode: inline carousel
+<div className="relative w-full h-full">
+  <Image src={currentSlide.imageUrl} alt={currentSlide.caption} fill className="object-cover rounded" />
+  {/* Navigation buttons at fixed positions */}
+</div>
+
+// Full-width mode: portal-based layers
+// Background layer (z-10): Full-screen image
+// Controls layer (z-30): Navigation buttons at configurable positions
+```
+
+**Key Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `carouselSlides` | CarouselSlide[] | [] | Array of slide items |
+| `carouselPrevIconUrl` | string | '' | Previous button custom icon |
+| `carouselNextIconUrl` | string | '' | Next button custom icon |
+| `carouselCaptionFontFamily` | string | '' | Font key for captions |
+| `carouselFullWidth` | boolean | false | Enable full-width background mode |
+
+**Full-Width Mode Button Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `carouselPrevX` | number | 5 | Prev button X position (% from left) |
+| `carouselPrevY` | number | 50 | Prev button Y position (% from top) |
+| `carouselNextX` | number | 95 | Next button X position (% from left) |
+| `carouselNextY` | number | 50 | Next button Y position (% from top) |
+| `carouselPrevWidth` | string | '' | Prev button width (vw units) |
+| `carouselPrevHeight` | string | '' | Prev button height (vh units) |
+| `carouselNextWidth` | string | '' | Next button width (vw units) |
+| `carouselNextHeight` | string | '' | Next button height (vh units) |
+
+**Button Rendering Modes:**
+| Condition | Rendering Style |
+|-----------|-----------------|
+| No custom icon | Default MDI chevron icon with backdrop blur |
+| Custom icon, no dimensions | Fixed 40x40 icon |
+| Custom icon + dimensions | Navigation-style: icon fills button, no backdrop |
+
+**CarouselSlide Structure:**
+```typescript
+{
+  id: string;
+  imageUrl: string;
+  caption: string;
+}
+```
+
+**Slide Transition Override Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `carouselSlideTransitionType` | `'fade' \| 'none' \| ''` | `''` | Transition type ('' = inherit from page transitions) |
+| `carouselSlideTransitionDurationMs` | `number \| ''` | `''` | Duration in ms ('' = inherit) |
+| `carouselSlideTransitionEasing` | `EasingFunction \| ''` | `''` | CSS easing function |
+| `carouselSlideTransitionOverlayColor` | `string` | `''` | Overlay color for fade ('' = inherit) |
+
+> **See:** [Project Transition Settings - Slide Transitions](project-transition-settings.md#slide-transitions-gallerycarousel) for cascade behavior.
+
+**Full-Width Mode Architecture:**
+```
+CarouselElement (full-width mode)
+├── Background layer (z-10): Fixed inset-0, image display
+├── Controls layer (z-30): Navigation buttons, caption
+│   └── Buttons have:
+│       - Configurable position (percentage-based)
+│       - Configurable dimensions (vw/vh units)
+│       - Draggable in constructor edit mode
+│       - Navigation-style rendering when icon+dimensions set
+└── Edit mode placeholder: Clickable element for selection
+```
+
+### Video Player
+
+**Purpose:** Embedded video playback with HTML5 controls.
+
+**Interactive Behavior:**
+- **Controls:** Play, pause, seek, volume, fullscreen
+- **Autoplay:** Starts automatically if `mediaAutoplay` is true
+- **Loop:** Repeats continuously if `mediaLoop` is true
+
+**Runtime Rendering:**
+```tsx
+<video
+  src={element.mediaUrl}
+  controls
+  autoPlay={Boolean(element.mediaAutoplay)}
+  loop={Boolean(element.mediaLoop)}
+  muted={Boolean(element.mediaMuted)}
+  playsInline
+  className="w-full h-full object-cover rounded"
+/>
+```
+
+**Key Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `mediaUrl` | string | "" | Video source URL |
+| `mediaAutoplay` | boolean | true | Auto-start playback |
+| `mediaLoop` | boolean | true | Loop continuously |
+| `mediaMuted` | boolean | true | Start muted |
+
+### Audio Player
+
+**Purpose:** Embedded audio playback with HTML5 controls.
+
+**Interactive Behavior:**
+- **Controls:** Play, pause, seek, volume
+- **Autoplay:** Starts automatically if `mediaAutoplay` is true
+
+**Runtime Rendering:**
+```tsx
+<audio
+  src={element.mediaUrl}
+  controls
+  autoPlay={Boolean(element.mediaAutoplay)}
+  loop={Boolean(element.mediaLoop)}
+  className="w-full"
+/>
+```
+
+**Key Properties:**
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `mediaUrl` | string | "" | Audio source URL |
+| `mediaAutoplay` | boolean | true | Auto-start playback |
+| `mediaLoop` | boolean | true | Loop continuously |
+| `mediaMuted` | boolean | false | Start muted (note: false by default) |
+
+### Logo
+
+**Purpose:** Display branding/logo image.
+
+**Interactive Behavior:**
+- **Static:** Typically non-interactive
+- **Click:** Can navigate to homepage or external URL
+
+**Runtime Rendering:** Uses `iconUrl` or `backgroundImageUrl` with `object-contain` scaling.
+
+### Popup
+
+**Purpose:** Modal dialog or overlay content.
+
+**Interactive Behavior:**
+- **Trigger:** Opened by element click or programmatic trigger
+- **Close:** Close button or click outside
+
+### Info Panel (info_panel)
+
+**Purpose:** Interactive panel with multiple sections for displaying images, 360° embeds, text content, and info spans. Similar to Gallery but with more flexible section-based layout and support for embedding external 360° viewers.
+
+**Architecture:**
+
+The Info Panel consists of three independently positioned components:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           Info Panel Architecture                        │
+│                                                                          │
+│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐  │
+│  │  Trigger Button  │    │    Info Panel    │    │ Image Detail     │  │
+│  │                  │    │    (Overlay)     │    │    Panel         │  │
+│  │  • xPercent      │    │                  │    │                  │  │
+│  │  • yPercent      │───▶│  • panelXPercent │───▶│ • detailXPercent │  │
+│  │  • iconUrl       │    │  • panelYPercent │    │ • detailYPercent │  │
+│  │  • hoverReveal   │    │  • sections[]    │    │ • 360° embeds    │  │
+│  │                  │    │  • spans, images │    │ • captions       │  │
+│  └──────────────────┘    └──────────────────┘    └──────────────────┘  │
+│        Click             Opens panel overlay    Card/360 click opens    │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Interactive Behavior:**
+- **Trigger Click:** Opens the Info Panel overlay with backdrop
+- **Disabled:** `infoPanelDisabled: true` suppresses panel opening in constructor interact mode and runtime presentations; runtime hover/focus/active visuals are preserved
+- **Default State:** `infoPanelOpenByDefault: true` opens every enabled matching Info Panel automatically when the page renders in constructor interact mode or runtime presentations
+- **Multiple Open Panels:** Runtime and constructor interact mode track open Info Panels by element ID. Image detail panels, fullscreen gallery state, and runtime media-section selected image state are scoped to the originating Info Panel ID, so multiple default-open panels can coexist without sharing detail/gallery state. Only one shared fullscreen backdrop is rendered for the group; backdrop clicks close the whole group, while each panel close button closes only that panel.
+- **Constructor Edit Preview:** In edit mode the Info Panel overlay is rendered
+  only from the selected Info Panel element, not from runtime `activeInfoPanel`
+  state. The Info Panel and Image Detail preview surfaces use non-blocking
+  pointer events so canvas elements remain selectable/draggable; only the
+  overlay drag handles stay interactive for panel positioning.
+- **Panel Backdrop Click:** Closes the panel
+- **Card/Thumbnail Click:** Uses section-level `mediaOpenMode`: `panel` opens the item in the side preview panel, and `fullscreen` opens the section's image/video/360 items in the shared fullscreen gallery overlay. Per-item `clickAction` can override this with `target_page` or `external_url`.
+- **Use as Screen Background:** Media items with `useAsBackground` replace the current page background with their image, video, or 360 embed content. This uses the same unified background renderer as `tour_pages.background_image_url`, `background_video_url`, and `background_embed_url`; destination override controls are disabled while this checkbox is enabled.
+- **Video Thumbnail Click:** Video items use `videoUrl`; Info Panel thumbnails render a muted first-frame video preview with a play badge instead of a generic placeholder, and open in the configured panel/fullscreen destination with native video controls
+- **Media Item Ordering:** Info Panel media sections render `section.images` in stored order, mixing image/video/360 items without regrouping by media type, so the presentation order matches the constructor sidebar order.
+- **360° Trigger Click:** Uses the same section-level `mediaOpenMode`; `panel` opens the 360 embed in the side preview panel and `fullscreen` opens it in the fullscreen gallery overlay without rendering runtime top-right controls or granting iframe fullscreen permission
+- **360° Embed Chrome:** 360 iframe URLs are normalized through
+  `buildChromeFreeEmbedUrl` before rendering. For Kuula embeds, internal viewer
+  chrome that duplicates platform controls is disabled with `fs=0` while
+  preserving playback/autorotate parameters from the source URL.
+- **Header/Title/Text/Span Click:** Can target an internal page or an external URL when configured
+- **Hover Reveal:** Trigger can use `hoverReveal` effect (appears on hover)
+- **Persist on Click:** With `hoverPersistOnClick`, trigger stays visible after click
+
+**Section Types:**
+
+The Info Panel uses a section-based layout with dynamic ordering. Each section instance has its own ID, settings, and data:
+
+| Section | Description | Per-Instance Data |
+|---------|-------------|-------------------|
+| `header` | Image header with text overlay | `headerImageUrl`, `headerText` |
+| `title` | Panel title text | `title` |
+| `text` | Body text content | `text` |
+| `spans` | Info badges grid | `spans[]`, `columns`, `gap` |
+| `cards` | Image cards grid | `images[]`, `columns`, `gap` |
+| `images` | Media viewer | `images[]` |
+
+`columns` is normalized on load from number-like values, including strings such as `"3"`, and clamped to the supported `1..6` range before rendering.
+
+**Click Destinations:**
+
+| Scope | Supported Destinations | Fields |
+|-------|------------------------|--------|
+| Cards/media section | `panel`, `fullscreen` | `mediaOpenMode` |
+| Image/card/video/360 item override | `target_page`, `external_url`, screen background | `clickAction`, `targetPageSlug`, `externalUrl`, `imageUrl`, `videoUrl`, `embedUrl`, `useAsBackground` |
+| Header/title/text section | `target_page`, `external_url` | `clickAction`, `targetPageSlug`, `externalUrl` |
+| Span item | `target_page`, `external_url` | `clickAction`, `targetPageSlug`, `externalUrl` |
+
+Internal Info Panel links use `targetPageSlug` and are included in `extractPageLinksAndElements`, so connected pages participate in neighbor preloading. Info Panel image/video/icon assets nested inside `infoPanelSections` are also recursively extracted for preloading.
+
+**Multiple Section Instances:**
+
+Unlike Gallery, Info Panel allows multiple instances of the same section type:
+
+```typescript
+infoPanelSections: [
+  { id: 'section-1', type: 'spans', columns: 3, gap: '8', spans: [...] },
+  { id: 'section-2', type: 'spans', columns: 2, gap: '12', spans: [...] },  // Second spans
+  { id: 'section-3', type: 'images', images: [...] },
+]
+```
+
+When a new `info_panel` element is created, default section templates are copied with fresh local IDs. This prevents multiple newly-added Info Panels from sharing the same template section IDs.
+
+**Runtime Rendering:**
+```tsx
+// Trigger button (uses hover reveal from Effects)
+<button onClick={openPanel}>
+  {element.iconUrl ? (
+    <img src={element.iconUrl} />
+  ) : (
+    <span>{element.infoPanelTriggerLabel || 'Info'}</span>
+  )}
+</button>
+
+// Panel overlay (positioned independently)
+<InfoPanelOverlay
+  element={element}
+  onClose={closePanel}
+  onImageClick={openDetailPanel}
+  onNavigateToPage={navigateBySlug}
+  onOpenExternalUrl={openExternalUrl}
+/>
+
+// Image detail panel (for cards and 360° embeds)
+<ImageDetailPanel
+  element={element}
+  image={selectedImage}
+  onClose={closeDetail}
+  cssVars={cssVars}
+/>
+```
+
+**Sizing parity:** `InfoPanelOverlay` and `ImageDetailPanel` must receive the same canvas CSS custom properties (`cssVars`, including `--cu`) and the same `letterboxStyles` in constructor and runtime. The image/360 detail panel uses canvas units for `detailWidth`, `detailHeight`, padding, border radius, and border width; missing `cssVars` causes constructor/runtime dimensions to diverge.
+
+**Iframe fullscreen behavior:** `ImageDetailPanel` first tries the browser
+Fullscreen API for the panel itself. If that is blocked because the
+presentation is embedded, it tries to fullscreen the embedding iframe when the
+parent is same-origin. For cross-origin parents, it posts a
+`tour-builder:request-fullscreen` message so controlled wrapper pages can
+fullscreen the iframe element:
+
+```html
+<iframe id="tour-frame" src="https://example.com/p/project" allow="fullscreen" allowfullscreen></iframe>
+<script>
+  window.addEventListener('message', async (event) => {
+    if (event.data?.type !== 'tour-builder:request-fullscreen') return;
+    await document.getElementById('tour-frame')?.requestFullscreen();
+  });
+</script>
+```
+
+If the browser still blocks parent fullscreen, the panel falls back to a local
+fullscreen state that fills the iframe viewport. Esc exits this local mode
+before closing the panel.
+
+When the whole presentation is already in browser fullscreen, image detail
+fullscreen uses local panel expansion instead of exiting the presentation's
+fullscreen element. Toggling the image detail fullscreen button returns to the
+configured side/detail panel view while keeping the presentation fullscreen.
+`ImageDetailPanel` renders through a body-level portal so it is not trapped by
+the canvas stacking context (`z-[46]`). In fullscreen image detail mode, the
+detail wrapper is raised above runtime global controls so the fullscreen image
+controls stay on top; normal detail panel mode keeps the lower shared overlay
+stacking order.
+
+**Key Properties:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `infoPanelTriggerLabel` | string | - | Label text for trigger button |
+| `infoPanelTriggerFontFamily` | string | - | Font for trigger label |
+| `infoPanelDisabled` | boolean | false | Disable panel opening |
+| `infoPanelOpenByDefault` | boolean | false | Open this panel automatically when the page renders |
+| `panelXPercent` | number | 30 | Panel X position (0-100) |
+| `panelYPercent` | number | 50 | Panel Y position (0-100) |
+| `panelWidth` | string | '400' | Panel width |
+| `panelHeight` | string | 'auto' | Panel height |
+| `panelBackgroundColor` | string | 'rgba(0,0,0,0.85)' | Panel background |
+| `panelOverlayColor` | string | 'rgba(0,0,0,0.3)' | Backdrop overlay |
+| `infoPanelSections` | array | DEFAULT_SECTIONS | Section instances |
+| `detailXPercent` | number | 70 | Detail panel X position |
+| `detailYPercent` | number | 50 | Detail panel Y position |
+| `detailWidth` | string | '500' | Detail panel width |
+| `detailHeight` | string | '400' | Detail panel height |
+
+**Section Styling Properties:**
+
+| Section | Style Properties |
+|---------|------------------|
+| Header | `infoPanelHeader[Color|FontSize|FontFamily|FontWeight|Padding|BorderRadius|TextAlign|Width|Height|MinHeight|MaxHeight]` |
+| Title | `panelTitle[Color|FontSize|FontFamily]`, `infoPanelTitle[BackgroundColor|Padding|FontWeight|TextAlign]` |
+| Text | `panelText[Color|FontSize|FontFamily]`, `infoPanelText[BackgroundColor|Padding|FontWeight|TextAlign]` |
+| Spans | `infoPanelSpan[BackgroundColor|Color|FontFamily|FontSize|FontWeight|Padding|BorderRadius|Gap|TextAlign]` |
+| Cards | `infoPanelCard[BackgroundColor|BorderRadius|AspectRatio|MinHeight|Gap]`, `infoPanelCardTitle[BackgroundColor|Color|FontFamily|FontSize|FontWeight|Padding]` |
+
+## Constructor vs Runtime Rendering
+
+| Aspect | Constructor | Runtime |
+|--------|-------------|---------|
+| **Positioning** | Drag-and-drop, resize handles | Fixed position via `xPercent`, `yPercent` |
+| **Editing** | Property panels, inline editing | Read-only display |
+| **Selection** | Click to select, multi-select | Click triggers actions |
+| **Transitions** | Preview button | Full playback with video |
+| **Appearance** | Visible at all times | Respects `appearDelaySec`, `appearDurationSec` |
+| **Navigation** | Simulated (no page switch) | Actual page navigation |
+
+### Unified Rendering Architecture
+
+Both Constructor and Runtime use a shared rendering architecture for WYSIWYG consistency:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Shared Rendering Components                            │
+│                                                                          │
+│  ┌────────────────────────────────────────────────────────────────────┐ │
+│  │                    UiElementRenderer                                │ │
+│  │                    (Main entry point)                               │ │
+│  │                                                                     │ │
+│  │   ├── useElementWrapperStyle (shared styling hook)                  │ │
+│  │   └── Per-type components:                                          │ │
+│  │       ├── NavigationElement   ├── GalleryElement                    │ │
+│  │       ├── InfoPanelElement    ├── DescriptionElement                │ │
+│  │       ├── CarouselElement     ├── LogoElement                       │ │
+│  │       ├── SpotElement         ├── VideoPlayerElement                │ │
+│  │       ├── AudioPlayerElement  └── PopupElement                      │ │
+│  └────────────────────────────────────────────────────────────────────┘ │
+│                              │                                           │
+│              ┌───────────────┴───────────────┐                          │
+│              ▼                               ▼                          │
+│     ┌────────────────┐              ┌────────────────┐                  │
+│     │  CanvasElement │              │ RuntimeElement │                  │
+│     │  (Constructor) │              │   (Runtime)    │                  │
+│     │                │              │                │                  │
+│     │ • Position     │              │ • Position     │                  │
+│     │ • Selection    │              │ • Effects      │                  │
+│     │ • Drag-drop    │              │ • Click events │                  │
+│     └────────────────┘              └────────────────┘                  │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Key Components:**
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `UiElementRenderer` | `components/UiElements/UiElementRenderer.tsx` | Unified rendering entry point |
+| `useElementWrapperStyle` | `components/UiElements/shared/useElementWrapperStyle.ts` | Consistent wrapper styling |
+| `NavigationElement` | `components/UiElements/elements/NavigationElement.tsx` | Navigation button rendering |
+| `GalleryElement` | `components/UiElements/elements/GalleryElement.tsx` | Gallery grid rendering |
+| (other per-type) | `components/UiElements/elements/*.tsx` | Type-specific rendering |
+| `CanvasElement` | `components/Constructor/CanvasElement.tsx` | Constructor wrapper (position, selection) |
+| `RuntimeElement` | `components/RuntimeElement.tsx` | Runtime wrapper (position, effects) |
+
+**Benefits:**
+- Single source of truth for element styling
+- WYSIWYG consistency between constructor and runtime
+- Per-type components enable focused maintenance
+- Shared styling hook eliminates divergence
+
+## Element Click Handler
+
+**File:** `frontend/src/components/RuntimePresentation.tsx`
+
+```typescript
+const handleElementClick = useCallback(
+  (element: any) => {
+    if (element.targetPageSlug) {
+      // Resolve slug to page
+      const targetPage = pages.find(p => p.slug === element.targetPageSlug);
+      if (!targetPage) return;
+
+      const isBack =
+        element.navType === 'back' || element.type === 'navigation_prev';
+      const transitionVideoUrl = element.transitionVideoUrl;
+      navigateToPage(targetPage.id, transitionVideoUrl, isBack);
+    }
+  },
+  [navigateToPage, pages],
+);
+```
+
+**Navigation Flow:**
+1. Check if element has `targetPageSlug`
+2. Resolve slug to page ID from loaded pages array
+3. Determine direction (`isBack`) from `navType` or element type
+4. If `transitionVideoUrl` exists, play transition overlay
+5. Otherwise, wait for target page images to load
+6. Switch to target page
+7. Add to page history
+
+## API Endpoints
+
+### Global Scope (element_type_defaults)
+
+**Route:** `backend/src/routes/element_type_defaults.ts`
+
+Uses `checkCrudPermissions('element_type_defaults')`.
+
+| Method | Endpoint | Permission | Description |
+|--------|----------|------------|-------------|
+| GET | `/api/element-type-defaults` | READ_PAGE_ELEMENTS | List all element types |
+| GET | `/api/element-type-defaults/:id` | READ_PAGE_ELEMENTS | Get element type details |
+| POST | `/api/element-type-defaults` | CREATE_PAGE_ELEMENTS | Create new type (admin) |
+| PUT | `/api/element-type-defaults/:id` | UPDATE_PAGE_ELEMENTS | Update defaults |
+| DELETE | `/api/element-type-defaults/:id` | DELETE_PAGE_ELEMENTS | Delete type (admin) |
+| GET | `/api/element-type-defaults/autocomplete` | READ_PAGE_ELEMENTS | Autocomplete search |
+| GET | `/api/element-type-defaults/count` | READ_PAGE_ELEMENTS | Count types |
+
+**Backwards Compatibility:** The old route `/api/ui-elements` is aliased to `/api/element-type-defaults`.
+
+**List Request:**
+```http
+GET /api/element-type-defaults?limit=1000&page=1&sort=asc&field=sort_order
+```
+
+**Update Request:**
+```http
+PUT /api/element-type-defaults/:id
+
+{
+  "id": "uuid",
+  "data": {
+    "element_type": "navigation_next",
+    "name": "Navigation Forward Button",
+    "sort_order": 1,
+    "is_active": true,
+    "default_settings_json": {
+      "label": "Navigation: Forward",
+      "navLabel": "Forward",
+      "navType": "forward",
+      ...
+    }
+  }
+}
+```
+
+### Project Scope (project_element_defaults)
+
+**Route:** `backend/src/routes/project_element_defaults.ts`
+
+| Method | Endpoint | Permission | Description |
+|--------|----------|------------|-------------|
+| GET | `/api/project-element-defaults` | READ_PAGE_ELEMENTS | List project defaults |
+| GET | `/api/project-element-defaults/:id` | READ_PAGE_ELEMENTS | Get specific default |
+| POST | `/api/project-element-defaults` | CREATE_PAGE_ELEMENTS | Create override |
+| PUT | `/api/project-element-defaults/:id` | UPDATE_PAGE_ELEMENTS | Update override |
+| DELETE | `/api/project-element-defaults/:id` | DELETE_PAGE_ELEMENTS | Delete override |
+| POST | `/api/project-element-defaults/:id/reset` | UPDATE_PAGE_ELEMENTS | Reset to global default |
+| GET | `/api/project-element-defaults/:id/diff` | READ_PAGE_ELEMENTS | Compare with global |
+
+**Reset to Global Request:**
+```http
+POST /api/project-element-defaults/:id/reset
+```
+
+**Diff from Global Response:**
+```json
+{
+  "isDifferent": true,
+  "hasGlobalDefault": true,
+  "projectDefault": { "id": "...", "settings_json": { ... }, ... },
+  "globalDefault": { "id": "...", "default_settings_json": { ... }, ... }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `isDifferent` | boolean | Whether settings differ from global |
+| `hasGlobalDefault` | boolean | Whether a matching global default exists |
+| `projectDefault` | object | Full project default record |
+| `globalDefault` | object \| null | Full global default record (or null if none) |
+
+#### Project Element Defaults Details Page
+
+**File:** `frontend/src/pages/project-element-defaults/[id].tsx`
+
+**Permission:** `UPDATE_PAGE_ELEMENTS`
+
+Uses the same shared `ElementSettings` components as the global defaults page.
+
+**Features:**
+- Tabbed interface: "General Settings" / "CSS Styles" / "Effects"
+- Form-based editing (no raw JSON textarea)
+- Type-specific form sections via shared components
+- "Reset to Global" button to restore global default values
+- Diff indicator when settings differ from global defaults
+- All changes immediately visible in constructor when editing project defaults
+
+**Note:** Prior to the ElementSettings refactoring, this page used a raw JSON textarea for editing `settings_json`. It now uses the same user-friendly form components as the global defaults page, providing a consistent editing experience across scopes.
+
+### Page Elements
+
+Page elements are stored inline in `tour_pages.ui_schema_json` and managed through the tour_pages API:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/tour_pages/:id` | Get page with elements in ui_schema_json |
+| PUT | `/api/tour_pages/:id` | Update page (includes ui_schema_json with elements) |
+
+**Note:** There is no separate `/api/page_elements` endpoint. Elements are part of the tour_pages record.
+
+## Frontend Implementation
+
+### TypeScript Types
+
+**File:** `frontend/src/types/constructor.ts`
+
+```typescript
+// Available element types in constructor (unified across all scopes)
+type CanvasElementType =
+  | 'navigation_next'
+  | 'navigation_prev'
+  | 'spot'
+  | 'description'
+  | 'gallery'
+  | 'carousel'
+  | 'logo'
+  | 'video_player'
+  | 'audio_player'
+  | 'popup'
+  | 'info_panel';  // Info panel with images/embeds
+
+// Navigation button direction
+type NavigationButtonKind = 'forward' | 'back';
+
+// Info panel section types
+type InfoPanelSectionType = 'header' | 'title' | 'text' | 'spans' | 'cards' | 'images';
+
+// Info panel section instance
+interface InfoPanelSectionInstance {
+  id: string;
+  type: InfoPanelSectionType;
+  columns?: number;
+  gap?: string;
+  spans?: InfoPanelInfoSpan[];
+  images?: InfoPanelImage[];
+  text?: string;
+  title?: string;
+  headerImageUrl?: string;
+  headerText?: string;
+}
+
+// Info panel info span
+interface InfoPanelInfoSpan {
+  id: string;
+  text: string;
+  iconUrl?: string;
+}
+
+// Info panel image/embed
+interface InfoPanelImage {
+  id: string;
+  imageUrl?: string;
+  embedUrl?: string;
+  caption?: string;
+  itemType?: 'image' | '360';
+  iconUrl?: string;
+}
+
+// Gallery card item
+interface GalleryCard {
+  id: string;
+  imageUrl: string;
+  title: string;
+  description: string;
+}
+
+// Carousel slide item
+interface CarouselSlide {
+  id: string;
+  imageUrl: string;
+  caption: string;
+}
+
+// Gallery info span (brief note badge)
+interface GalleryInfoSpan {
+  id: string;
+  text: string;
+}
+
+// Base element with positioning
+interface BaseCanvasElement {
+  id: string;
+  type: CanvasElementType | string;
+  label?: string;
+  xPercent?: number;
+  yPercent?: number;
+  // Styling fields
+  width?: string;
+  height?: string;
+  // ... other style properties
+  appearDelaySec?: number;
+  appearDurationSec?: number | null;
+}
+
+// Full element with all content fields
+interface CanvasElement extends BaseCanvasElement {
+  // Navigation fields
+  navLabel?: string;
+  navLabelFontFamily?: string;  // Font key for label text
+  navType?: NavigationButtonKind;
+  navDisabled?: boolean;
+  targetPageSlug?: string;  // Slug-based navigation (consistent across environments)
+  transitionVideoUrl?: string;
+  transitionReverseMode?: 'auto_reverse' | 'separate_video';
+  reverseVideoUrl?: string;
+  transitionDurationSec?: number;
+
+  // Tooltip fields
+  tooltipTitle?: string;
+  tooltipText?: string;
+  tooltipTitleFontFamily?: string;
+  tooltipTextFontFamily?: string;
+
+  // Description fields
+  descriptionTitle?: string;
+  descriptionText?: string;
+  descriptionTitleFontSize?: string;
+  descriptionTextFontSize?: string;
+  descriptionTitleFontFamily?: string;
+  descriptionTextFontFamily?: string;
+  descriptionTitleColor?: string;
+  descriptionTextColor?: string;
+  // Note: Background color uses the shared backgroundColor property from CSS Styles
+
+  // Media fields
+  mediaUrl?: string;
+  mediaAutoplay?: boolean;
+  mediaLoop?: boolean;
+  mediaMuted?: boolean;
+
+  // Gallery fields
+  galleryCards?: GalleryCard[];
+  galleryHeaderImageUrl?: string;
+  galleryTitle?: string;
+  galleryInfoSpans?: GalleryInfoSpan[];
+  galleryColumns?: number;
+  galleryTitleFontFamily?: string;
+  galleryTextFontFamily?: string;  // Font for card titles, descriptions, and info spans
+  // Gallery header dimensions
+  galleryHeaderWidth?: string;
+  galleryHeaderHeight?: string;
+  galleryHeaderMinHeight?: string;
+  galleryHeaderMaxHeight?: string;
+  // Gallery card dimensions
+  galleryCardWidth?: string;
+  galleryCardHeight?: string;
+  galleryCardMinHeight?: string;
+  galleryCardAspectRatio?: string;
+  // Gallery carousel navigation
+  galleryCarouselPrevIconUrl?: string;
+  galleryCarouselNextIconUrl?: string;
+  galleryCarouselBackIconUrl?: string;
+  galleryCarouselBackLabel?: string;
+  galleryCarouselPrevX?: number;
+  galleryCarouselPrevY?: number;
+  galleryCarouselNextX?: number;
+  galleryCarouselNextY?: number;
+  galleryCarouselBackX?: number;
+  galleryCarouselBackY?: number;
+  galleryCarouselPrevWidth?: string;
+  galleryCarouselPrevHeight?: string;
+  galleryCarouselNextWidth?: string;
+  galleryCarouselNextHeight?: string;
+  galleryCarouselBackWidth?: string;
+  galleryCarouselBackHeight?: string;
+  // Gallery section text alignment (default: 'center')
+  galleryHeaderTextAlign?: 'left' | 'center' | 'right';
+  galleryTitleTextAlign?: 'left' | 'center' | 'right';
+  gallerySpanTextAlign?: 'left' | 'center' | 'right';
+
+  // Carousel fields
+  carouselSlides?: CarouselSlide[];
+  carouselPrevIconUrl?: string;
+  carouselNextIconUrl?: string;
+  carouselCaptionFontFamily?: string;
+  carouselFullWidth?: boolean;
+  // Carousel button positions (percentage 0-100, for full-width mode)
+  carouselPrevX?: number;
+  carouselPrevY?: number;
+  carouselNextX?: number;
+  carouselNextY?: number;
+  // Carousel button dimensions (CSS values like '3vw', '5vh')
+  carouselPrevWidth?: string;
+  carouselPrevHeight?: string;
+  carouselNextWidth?: string;
+  carouselNextHeight?: string;
+  // Carousel slide transition override (inherits from page transitions if not set)
+  carouselSlideTransitionType?: 'fade' | 'none' | '';
+  carouselSlideTransitionDurationMs?: number | '';
+  carouselSlideTransitionEasing?: EasingFunction | '';
+  carouselSlideTransitionOverlayColor?: string;
+
+  // Gallery slide transition override (for fullscreen carousel overlay)
+  gallerySlideTransitionType?: 'fade' | 'none' | '';
+  gallerySlideTransitionDurationMs?: number | '';
+  gallerySlideTransitionEasing?: EasingFunction | '';
+  gallerySlideTransitionOverlayColor?: string;
+
+  // Popup fields
+  popupTitle?: string;
+  popupContent?: string;
+
+  // Info Panel fields
+  infoPanelTriggerLabel?: string;
+  infoPanelTriggerFontFamily?: string;
+  infoPanelDisabled?: boolean;
+  infoPanelOpenByDefault?: boolean;
+  panelTitle?: string;
+  panelText?: string;
+  infoPanelHeaderImageUrl?: string;
+  infoPanelHeaderText?: string;
+  // Panel position & styling
+  panelXPercent?: number;
+  panelYPercent?: number;
+  panelWidth?: string;
+  panelHeight?: string;
+  panelBackgroundColor?: string;
+  panelBorderRadius?: string;
+  panelPadding?: string;
+  panelBackdropBlur?: string;
+  panelOverlayColor?: string;
+  panelBorderWidth?: string;
+  panelBorderColor?: string;
+  panelBorderStyle?: 'none' | 'solid' | 'dashed' | 'dotted';
+  infoPanelSectionGap?: string;
+  // Section instances
+  infoPanelSections?: InfoPanelSectionInstance[];
+  // Header section styles
+  infoPanelHeaderBackgroundColor?: string;
+  infoPanelHeaderColor?: string;
+  infoPanelHeaderFontFamily?: string;
+  infoPanelHeaderFontSize?: string;
+  infoPanelHeaderFontWeight?: string;
+  infoPanelHeaderPadding?: string;
+  infoPanelHeaderBorderRadius?: string;
+  infoPanelHeaderTextAlign?: 'left' | 'center' | 'right';
+  infoPanelHeaderWidth?: string;
+  infoPanelHeaderHeight?: string;
+  infoPanelHeaderMinHeight?: string;
+  infoPanelHeaderMaxHeight?: string;
+  // Title section styles
+  panelTitleColor?: string;
+  panelTitleFontSize?: string;
+  panelTitleFontFamily?: string;
+  infoPanelTitleBackgroundColor?: string;
+  infoPanelTitlePadding?: string;
+  infoPanelTitleFontWeight?: string;
+  infoPanelTitleTextAlign?: 'left' | 'center' | 'right';
+  // Text section styles
+  panelTextColor?: string;
+  panelTextFontSize?: string;
+  panelTextFontFamily?: string;
+  // Span section styles
+  infoPanelSpanBackgroundColor?: string;
+  infoPanelSpanColor?: string;
+  infoPanelSpanFontFamily?: string;
+  infoPanelSpanFontSize?: string;
+  infoPanelSpanPadding?: string;
+  infoPanelSpanBorderRadius?: string;
+  infoPanelSpanGap?: string;
+  // Card section styles
+  infoPanelCardBackgroundColor?: string;
+  infoPanelCardBorderRadius?: string;
+  infoPanelCardAspectRatio?: string;
+  infoPanelCardMinHeight?: string;
+  infoPanelCardGap?: string;
+  infoPanelCardTitleBackgroundColor?: string;
+  infoPanelCardTitleColor?: string;
+  infoPanelCardTitleFontFamily?: string;
+  infoPanelCardTitleFontSize?: string;
+  infoPanelCardTitlePadding?: string;
+  // Media section
+  infoPanelImagesPreviewHeight?: string;
+  infoPanelImagesThumbnailSize?: string;
+  // Image Detail Panel
+  detailXPercent?: number;
+  detailYPercent?: number;
+  detailWidth?: string;
+  detailHeight?: string;
+  detailBackgroundColor?: string;
+  detailBorderRadius?: string;
+  detailPadding?: string;
+  detailCaptionFontFamily?: string;
+  detailBorderWidth?: string;
+  detailBorderColor?: string;
+  detailBorderStyle?: 'none' | 'solid' | 'dashed' | 'dotted';
+}
+
+// Element type default from database (renamed from UiElementDefault)
+interface ElementTypeDefault {
+  id: string;
+  element_type?: string;
+  is_active?: boolean;
+  default_settings_json?: string | Record<string, unknown>;
+}
+```
+
+### Element Settings Components
+
+**Directory:** `frontend/src/components/ElementSettings/`
+
+The platform uses shared form components for editing element settings across all three scopes (global, project, instance). This ensures UI consistency and reduces code duplication.
+
+#### Component Structure
+
+```
+frontend/src/components/ElementSettings/
+├── index.ts                              # Barrel exports
+├── types.ts                              # Shared TypeScript types
+├── useElementSettingsForm.ts             # Form state management hook
+├── ElementSettingsTabs.tsx               # Tab navigation (regular + compact)
+├── CommonSettingsSection.tsx             # Label, position, appearance timing
+├── CommonSettingsSectionCompact.tsx      # Label, position (compact for sidebar)
+├── StyleSettingsSection.tsx              # CSS properties (full width)
+├── StyleSettingsSectionCompact.tsx       # CSS properties (compact for sidebar)
+├── EffectsSettingsSection.tsx            # Visual effects (full width)
+├── EffectsSettingsSectionCompact.tsx     # Visual effects (compact for sidebar)
+├── NavigationSettingsSection.tsx         # Navigation element settings
+├── NavigationSettingsSectionCompact.tsx  # Navigation (compact)
+├── DescriptionSettingsSection.tsx        # Description element settings
+├── DescriptionSettingsSectionCompact.tsx # Description (compact)
+├── MediaSettingsSection.tsx              # Video/audio player settings
+├── MediaSettingsSectionCompact.tsx       # Media (compact)
+├── GallerySettingsSection.tsx            # Gallery cards editor
+├── GallerySettingsSectionCompact.tsx     # Gallery (compact)
+├── CarouselSettingsSection.tsx           # Carousel slides editor
+├── CarouselSettingsSectionCompact.tsx    # Carousel (compact)
+└── GalleryCarouselSettingsSectionCompact.tsx  # Gallery carousel nav settings (compact)
+```
+
+#### useElementSettingsForm Hook
+
+**File:** `frontend/src/components/ElementSettings/useElementSettingsForm.ts`
+
+Manages ~60 form state fields for element settings:
+
+```typescript
+const form = useElementSettingsForm({ elementType: 'navigation_next' });
+
+// Apply settings from JSON (e.g., from API response)
+form.applySettings(item.settings_json);
+
+// Build settings JSON for saving
+const settings = form.buildSettingsJson();
+
+// Type detection helpers
+if (form.isNavigationType) { /* show navigation fields */ }
+if (form.isInfoPanelType) { /* show info panel fields */ }
+
+// Gallery/carousel operations
+form.addGalleryCard();
+form.removeGalleryCard(cardId);
+form.updateGalleryCard(cardId, 'title', 'New Title');
+```
+
+#### Tab Navigation
+
+Two variants for different contexts:
+
+```typescript
+// Full-size tabs for admin pages
+import { ElementSettingsTabs } from '../../components/ElementSettings';
+
+const SETTINGS_TABS = [
+  { id: 'general', label: 'General Settings' },
+  { id: 'css', label: 'CSS Styles' },
+  { id: 'effects', label: 'Effects' },
+];
+
+<ElementSettingsTabs
+  activeTab={activeTab}
+  onTabChange={setActiveTab}
+  tabs={SETTINGS_TABS}
+/>
+
+// Compact tabs for constructor sidebar
+import { ElementSettingsTabsCompact } from '../../components/ElementSettings';
+
+<ElementSettingsTabsCompact
+  activeTab={elementEditorTab}
+  onTabChange={setElementEditorTab}
+  tabs={SETTINGS_TABS}
+/>
+```
+
+#### Context-Aware Rendering
+
+Components accept a `context` prop to render differently based on usage:
+
+| Context | Asset Selection | Input Style |
+|---------|-----------------|-------------|
+| `global` | Text input (URLs) | Full-width inputs |
+| `project` | Text input (URLs) | Full-width inputs |
+| `constructor` | Asset dropdown (from project assets) | Compact inputs |
+
+### Admin Pages
+
+#### Element Type Defaults List Page
+
+**File:** `frontend/src/pages/element-type-defaults.tsx`
+
+**Permission:** `READ_PAGE_ELEMENTS`
+
+**Features:**
+- Lists all 12 predefined element types
+- Shows name, element_type (humanized), sort_order, is_active status
+- Links to detail page for editing
+
+```typescript
+// Fetch all element types ordered by sort_order
+const response = await axios.get(
+  '/element-type-defaults?limit=1000&page=1&sort=asc&field=sort_order'
+);
+```
+
+#### Element Type Default Details Page
+
+**File:** `frontend/src/pages/element-type-defaults/[id].tsx`
+
+**Permission:** `UPDATE_PAGE_ELEMENTS`
+
+Uses shared `ElementSettings` components with `useElementSettingsForm` hook.
+
+**Features:**
+- Tabbed interface: "General Settings" / "CSS Styles" / "Effects"
+- Edit default settings for any element type
+- Type-specific form sections (via shared components):
+  - **CommonSettingsSection:** Label, position (X%, Y%), appearance timing
+  - **StyleSettingsSection:** Dimensions, spacing, typography, effects
+  - **NavigationSettingsSection:** Icon, label, nav type, transition settings
+  - **DescriptionSettingsSection:** Title, text, fonts, colors
+  - **GallerySettingsSection:** Card array editor (add/remove cards)
+  - **CarouselSettingsSection:** Slide array editor, prev/next icons
+  - **MediaSettingsSection:** URL, autoplay, loop, muted flags
+  - **InfoPanelSettingsSection:** Section ordering, spans/images data, panel/detail styling
+
+### Constructor Integration
+
+**File:** `frontend/src/pages/constructor.tsx`
+
+#### Element Editor Tabs
+
+The constructor's element editing sidebar now includes tabs for organizing settings:
+
+```
+┌───────────────────────────────────────────┐
+│ [General] [CSS Styles] [Effects]          │  ← Tab bar (ElementSettingsTabsCompact)
+├───────────────────────────────────────────┤
+│ Content based on selected tab             │
+│                                           │
+│ General: label, icon, target page,        │
+│          type-specific content            │
+│                                           │
+│ CSS: width, height, border,               │
+│      margin, padding, opacity, etc.       │
+│                                           │
+│ Effects: visual effects, animations,      │
+│          transitions, transforms          │
+└───────────────────────────────────────────┘
+```
+
+**Implementation:**
+```typescript
+import {
+  ElementSettingsTabsCompact,
+  StyleSettingsSectionCompact,
+  EffectsSettingsSectionCompact,
+  extractNumericValue,
+} from '../../components/ElementSettings';
+
+const [elementEditorTab, setElementEditorTab] = useState<'general' | 'css' | 'effects'>('general');
+
+// Tab navigation
+<ElementSettingsTabsCompact
+  activeTab={elementEditorTab}
+  onTabChange={setElementEditorTab}
+  tabs={[
+    { id: 'general', label: 'General' },
+    { id: 'css', label: 'CSS Styles' },
+    { id: 'effects', label: 'Effects' },
+  ]}
+/>
+
+// CSS Styles tab content
+{elementEditorTab === 'css' && (
+  <StyleSettingsSectionCompact
+    values={{
+      width: extractNumericValue(selectedElement.width),
+      height: extractNumericValue(selectedElement.height),
+      // ... other CSS properties
+    }}
+    onChange={(prop, value) => {
+      // Handle unit conversion (vw, vh, px)
+      updateSelectedElement({ [prop]: formattedValue });
+    }}
+  />
+)}
+```
+
+**CSS Unit Conventions:**
+| Property | Unit | Example | Auto-Normalization |
+|----------|------|---------|-------------------|
+| width, minWidth, maxWidth | vw | `24vw` | `"24"` → `"24vw"` |
+| height, minHeight, maxHeight | vh | `8vh` | `"8"` → `"8vh"` |
+| border | (complex) | `2px solid currentColor` | No (preserved as-is) |
+| borderRadius | px | `8px` | `"8"` → `"8px"` |
+| Gallery fontSize/padding/gap | rem | `0.875rem` | `"0.875"` → `"0.875rem"` |
+
+**Note:** Unit normalization happens both at form save time (via `toUnitValue` in `types.ts`) and at render time (via `buildElementStyle` and gallery section style builders). Values with existing units, CSS functions, or complex values are preserved as-is.
+
+#### Loading Project Defaults
+
+The constructor fetches project-specific element defaults on load:
+
+```typescript
+// Fetch project element defaults (not global!)
+const uiElementsResponse = await axios.get(
+  `/project-element-defaults?projectId=${projectId}&limit=200&page=1&sort=asc&field=sort_order`,
+);
+
+// Normalize and build lookup map using shared utilities from types/constructor.ts
+const uiElementRows = Array.isArray(uiElementsResponse?.data?.rows)
+  ? uiElementsResponse.data.rows
+  : [];
+const normalizedDefaults = uiElementRows
+  .map((row) => normalizeElementDefault(row))
+  .filter((d): d is NormalizedElementDefault => d !== null);
+const defaultsByType = buildElementDefaultsMap(normalizedDefaults);
+setUiElementDefaultsByType(defaultsByType);
+```
+
+#### Shared Normalization Utilities
+
+**File:** `frontend/src/types/constructor.ts`
+
+```typescript
+// Handles both settings_json (project) and default_settings_json (global)
+function normalizeElementDefault(row: Record<string, unknown>): NormalizedElementDefault | null {
+  const elementType = String(row.element_type || '').trim();
+  if (!elementType) return null;
+
+  const rawSettings = row.settings_json ?? row.default_settings_json;
+  let settings: Partial<CanvasElement> = {};
+
+  if (typeof rawSettings === 'string') {
+    try { settings = JSON.parse(rawSettings); } catch { settings = {}; }
+  } else if (rawSettings && typeof rawSettings === 'object') {
+    settings = rawSettings as Partial<CanvasElement>;
+  }
+
+  return { id: String(row.id || ''), element_type: elementType, settings };
+}
+
+// Build element type to defaults lookup map
+function buildElementDefaultsMap(defaults: NormalizedElementDefault[]) {
+  const map: Partial<Record<CanvasElementType, Partial<CanvasElement>>> = {};
+  for (const def of defaults) {
+    if (isCanvasElementType(def.element_type)) {
+      map[def.element_type] = def.settings;
+    }
+  }
+  return map;
+}
+```
+
+#### Creating New Elements
+
+The constructor creates elements with inline defaults, then merges with project defaults:
+
+```typescript
+// Create element with inline/hardcoded defaults
+const createDefaultElement = (
+  type: CanvasElementType,
+  index: number,
+): CanvasElement => {
+  const base: CanvasElement = {
+    id: createLocalId(),
+    type,
+    label: labelByType[type],
+    xPercent: clamp(12 + index * 4, 5, 80),  // Staggered positioning
+    yPercent: clamp(16 + index * 6, 8, 85),
+    appearDelaySec: 0,
+    appearDurationSec: null,
+  };
+
+  // Type-specific defaults added inline
+  if (type === 'gallery') {
+    return { ...base, galleryCards: [{ id, imageUrl: '', title: 'Card 1', description: '' }] };
+  }
+  // ... other types
+  return base;
+};
+
+// Add element with project defaults applied
+const addElement = (type: CanvasElementType) => {
+  const baseElement = createDefaultElement(type, elements.length);
+  const nextElement = mergeElementWithDefaults(
+    baseElement,
+    uiElementDefaultsByType[type],  // Project defaults (or undefined)
+  );
+  setElements((prev) => [...prev, nextElement]);
+};
+```
+
+#### Loading Existing Elements
+
+When loading elements from `ui_schema_json`, existing values take precedence over defaults:
+
+```typescript
+// mergeElementWithDefaults with preferElementValues: true
+// → Element's stored values are preserved, defaults only fill missing fields
+return mergeElementWithDefaults(
+  normalizedElement,
+  uiElementDefaultsByType[elementType],
+  { preferElementValues: true },  // Existing element values take precedence
+);
+```
+
+#### Merge Logic
+
+```typescript
+// Merge instance values with defaults (from project scope)
+const mergeElementWithDefaults = (
+  element: CanvasElement,
+  defaults?: Partial<CanvasElement>,
+  options?: { preferElementValues?: boolean },
+): CanvasElement => {
+  if (!defaults) return element;  // Graceful handling if no project defaults
+
+  const preferElementValues = Boolean(options?.preferElementValues);
+  const base = preferElementValues ? defaults : element;
+  const override = preferElementValues ? element : defaults;
+
+  return {
+    ...base,
+    ...override,
+    id: element.id,       // Always preserve element id
+    type: element.type,   // Always preserve element type
+  };
+};
+```
+
+## Scope Comparison
+
+| Aspect | Global (element_type_defaults) | Project (project_element_defaults) | Page Elements (ui_schema_json) |
+|--------|-------------------------------|-----------------------------------|-------------------------------|
+| **Purpose** | Platform-wide defaults | Project-specific overrides | Page-specific instances |
+| **Count** | 11 auto-seeded types | 11 per project (auto-snapshotted) | Unlimited per page |
+| **Storage** | `settings_json` (TEXT) | `settings_json` (TEXT) | `tour_pages.ui_schema_json` |
+| **Field Alias** | `default_settings_json` (model alias) | `settings_json` (direct) | N/A (inline JSON) |
+| **Element Type** | TEXT (globally unique) | TEXT (unique per project) | TEXT (flexible) |
+| **Parent** | None | projects (CASCADE on delete) | tour_pages (inline storage) |
+| **Position Data** | In settings_json | In settings_json | Directly in element object |
+| **Creation** | Auto-seeded on first API access | Auto-snapshotted on project create | Manual via constructor |
+| **Management** | Admin UI (/element-type-defaults) | Project settings (/project-element-defaults) | Constructor drag-drop |
+| **API Query** | `/element-type-defaults` | `/project-element-defaults?projectId=xxx` | `/tour_pages/:id` |
+| **Inheritance** | Base layer (template) | Copies from global, can diverge | Merges with project defaults |
+
+### Project Element Defaults API Filtering
+
+The `project_element_defaults` API implements custom filtering by project:
+
+```bash
+# Filter by project UUID
+GET /api/project-element-defaults?projectId=<uuid>
+
+# Filter by project name (case-insensitive)
+GET /api/project-element-defaults?project=<project-name>
+
+# Both params supported, can use pipe for multiple values
+GET /api/project-element-defaults?projectId=uuid1|uuid2
+```
+
+## Settings Inheritance Flow
+
+### New Element Creation
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ User clicks "Add Navigation" in constructor                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. createDefaultElement('navigation_next', index)               │
+│     → Creates base element with hardcoded defaults:              │
+│        - id: generated UUID                                      │
+│        - type: 'navigation_next'                                 │
+│        - label: 'Navigation: Forward'                            │
+│        - xPercent/yPercent: staggered position                   │
+│        - Type-specific fields (navLabel, navType, etc.)          │
+│                                                                  │
+│  2. mergeElementWithDefaults(base, uiElementDefaultsByType[type])│
+│     → Looks up project defaults from pre-loaded map              │
+│     → If found: merges project settings over hardcoded base      │
+│     → If not found: returns hardcoded base unchanged             │
+│                                                                  │
+│  3. Element added to state with merged values                    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Loading Existing Elements
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Page loads with existing elements in ui_schema_json              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. Parse ui_schema_json.elements[]                              │
+│     → Normalize each element's field values                      │
+│                                                                  │
+│  2. mergeElementWithDefaults(element, defaults,                  │
+│       { preferElementValues: true })                             │
+│     → Element's stored values TAKE PRECEDENCE                    │
+│     → Project defaults only fill MISSING fields                  │
+│                                                                  │
+│  3. Display elements with complete merged settings               │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow Summary
+
+```
+┌────────────────────┐
+│ Global Defaults    │ (element_type_defaults)
+│ - 11 auto-seeded   │
+│ - Platform-wide    │
+└─────────┬──────────┘
+          │
+          │ snapshotGlobalDefaults() on project creation
+          ▼
+┌────────────────────┐
+│ Project Defaults   │ (project_element_defaults)
+│ - Copied from      │
+│   global on create │
+│ - Customizable     │
+└─────────┬──────────┘
+          │
+          │ Constructor loads via /project-element-defaults?projectId=xxx
+          │ buildElementDefaultsMap() creates lookup table
+          ▼
+┌────────────────────┐
+│ Constructor State  │ (uiElementDefaultsByType)
+│ - In-memory map    │
+│ - Used for merge   │
+└─────────┬──────────┘
+          │
+          │ mergeElementWithDefaults() on add/load
+          ▼
+┌────────────────────┐
+│ Page Elements      │ (tour_pages.ui_schema_json)
+│ - Stored with full │
+│   merged settings  │
+│ - No refs to       │
+│   defaults         │
+└────────────────────┘
+```
+
+## Asset Preloading
+
+**File:** `frontend/src/config/preload.config.ts`
+
+UI element assets are automatically extracted for preloading:
+
+```typescript
+assetFields: {
+  all: [
+    'iconUrl',           // Navigation, tooltips, info panel triggers
+    'imageUrl',          // Gallery, carousel, info panel images
+    'mediaUrl',          // Video/audio players
+    'videoUrl',
+    'audioUrl',
+    'transitionVideoUrl',
+    'backgroundImageUrl',
+    'reverseVideoUrl',
+    'carouselPrevIconUrl',
+    'carouselNextIconUrl',
+    'infoPanelHeaderImageUrl',  // Info panel header image
+    'src',               // Generic source URLs
+    'url',               // Generic URLs
+    'poster',            // Video poster images
+    'thumbnail'          // Thumbnail images
+  ],
+  images: [              // Image-only fields for pre-decode
+    'iconUrl',
+    'imageUrl',
+    'backgroundImageUrl',
+    'carouselPrevIconUrl',
+    'carouselNextIconUrl',
+    'infoPanelHeaderImageUrl',
+    'src'
+  ],
+  nested: ['galleryCards', 'carouselSlides', 'infoPanelSections'],
+  nestedUrlFields: ['imageUrl', 'videoUrl', 'iconUrl', 'headerImageUrl', 'embedUrl']
+}
+```
+
+**Preload Priority by Asset Type:**
+| Asset Type | Priority Bonus | Description |
+|------------|----------------|-------------|
+| Transition video | +150 | Highest - needed immediately on navigation click |
+| Image | +100 | Backgrounds and icons |
+| Audio | +50 | Background audio |
+| Video | +30 | Background videos can stream progressively |
+
+**Note:** `maxNeighborDepth` defaults to 1 (immediate neighbors only). Current page assets get base priority 1000, neighbors get 500.
+
+The preload orchestrator:
+1. Extracts all asset URLs from element configurations using `extractPageLinksAndElements()`
+2. Fetches S3 presigned URLs via `POST /api/file/presign` (max 50 per batch, 1-hour expiry)
+3. Downloads assets directly from S3 and stores in Cache API (dual key: download URL + storage key)
+4. Creates blob URLs and stores in `readyBlobUrlsRef` (dual key: download URL + storage key) for O(1) instant lookup
+5. Pre-decodes images before page transitions using the blob URLs
+6. Manages concurrent downloads (max 3)
+
+**Storage Key Mapping:** Assets are cached by canonical storage key (e.g., `assets/project/icon.png`) in addition to download URLs. This ensures cache hits even when presigned URL signatures change.
+
+**Blob URL Rendering:** When displaying preloaded assets, use native `<img>` tags for blob URLs instead of Next.js `<Image>` to prevent re-fetching on component re-renders (see `assets-preloading.md` for details).
+
+## File References
+
+### Backend
+
+| File | Purpose |
+|------|---------|
+| `backend/src/db/models/element_type_defaults.js` | Global scope model |
+| `backend/src/db/models/project_element_defaults.js` | Project scope model |
+| `backend/src/db/models/tour_pages.js` | Tour pages model (elements in ui_schema_json) |
+| `backend/src/db/api/element_type_defaults.ts` | Global scope DB API + auto-seed |
+| `backend/src/db/api/project_element_defaults.ts` | Project scope DB API + snapshot |
+| `backend/src/routes/element_type_defaults.ts` | Global scope routes |
+| `backend/src/routes/project_element_defaults.ts` | Project scope routes |
+| `backend/src/services/element_type_defaults.ts` | Global scope service |
+| `backend/src/services/project_element_defaults.ts` | Project scope service |
+
+### Frontend
+
+| File | Purpose |
+|------|---------|
+| `frontend/src/types/constructor.ts` | TypeScript types |
+| `frontend/src/pages/element-type-defaults.tsx` | Global defaults admin list |
+| `frontend/src/pages/element-type-defaults/[id].tsx` | Global defaults admin details |
+| `frontend/src/pages/project-element-defaults/[id].tsx` | Project defaults details |
+| `frontend/src/pages/constructor.tsx` | Element editor (manages elements in ui_schema_json) |
+| `frontend/src/components/UiElements/defaults.ts` | Frontend fallback defaults |
+| `frontend/src/config/preload.config.ts` | Asset preloading config |
+
+#### Element Rendering Components
+
+| File | Purpose |
+|------|---------|
+| `frontend/src/components/UiElements/UiElementRenderer.tsx` | Unified rendering entry point |
+| `frontend/src/components/UiElements/shared/useElementWrapperStyle.ts` | Shared wrapper styling hook |
+| `frontend/src/components/UiElements/elements/NavigationElement.tsx` | Navigation button (next/prev) |
+| `frontend/src/components/UiElements/elements/GalleryElement.tsx` | Image gallery grid |
+| `frontend/src/components/UiElements/elements/DescriptionElement.tsx` | Description text block |
+| `frontend/src/components/UiElements/elements/CarouselElement.tsx` | Image carousel |
+| `frontend/src/components/UiElements/elements/LogoElement.tsx` | Logo display |
+| `frontend/src/components/UiElements/elements/SpotElement.tsx` | Hotspot/clickable area |
+| `frontend/src/components/UiElements/elements/VideoPlayerElement.tsx` | Embedded video player |
+| `frontend/src/components/UiElements/elements/AudioPlayerElement.tsx` | Embedded audio player |
+| `frontend/src/components/UiElements/elements/PopupElement.tsx` | Modal/popup dialog |
+| `frontend/src/components/UiElements/elements/InfoPanelElement.tsx` | Info panel trigger button |
+| `frontend/src/components/UiElements/InfoPanelOverlay.tsx` | Info panel overlay with sections; supports `renderBackdrop` and `onBackdropClose` so multiple open panels share one backdrop |
+| `frontend/src/components/UiElements/ImageDetailPanel.tsx` | Image detail panel for cards/360° |
+| `frontend/src/components/Constructor/CanvasElement.tsx` | Constructor wrapper (position, selection, drag) |
+| `frontend/src/components/RuntimeElement.tsx` | Runtime wrapper (position, effects) |
+
+#### Element Settings Components
+
+| File | Purpose |
+|------|---------|
+| `frontend/src/components/ElementSettings/index.ts` | Barrel exports |
+| `frontend/src/components/ElementSettings/types.ts` | Shared TypeScript types |
+| `frontend/src/components/ElementSettings/useElementSettingsForm.ts` | Form state management hook |
+| `frontend/src/components/ElementSettings/ElementSettingsTabs.tsx` | Tab navigation component |
+| `frontend/src/components/ElementSettings/CommonSettingsSection.tsx` | Common settings (label, position, timing) |
+| `frontend/src/components/ElementSettings/CommonSettingsSectionCompact.tsx` | Common settings (compact) |
+| `frontend/src/components/ElementSettings/StyleSettingsSection.tsx` | CSS styling (full-width version) |
+| `frontend/src/components/ElementSettings/StyleSettingsSectionCompact.tsx` | CSS styling (compact version) |
+| `frontend/src/components/ElementSettings/EffectsSettingsSection.tsx` | Visual effects (full-width) |
+| `frontend/src/components/ElementSettings/EffectsSettingsSectionCompact.tsx` | Visual effects (compact) |
+| `frontend/src/components/ElementSettings/NavigationSettingsSection.tsx` | Navigation element fields |
+| `frontend/src/components/ElementSettings/NavigationSettingsSectionCompact.tsx` | Navigation (compact) |
+| `frontend/src/components/ElementSettings/DescriptionSettingsSection.tsx` | Description element fields |
+| `frontend/src/components/ElementSettings/DescriptionSettingsSectionCompact.tsx` | Description (compact) |
+| `frontend/src/components/ElementSettings/MediaSettingsSection.tsx` | Video/audio player fields |
+| `frontend/src/components/ElementSettings/MediaSettingsSectionCompact.tsx` | Media (compact) |
+| `frontend/src/components/ElementSettings/GallerySettingsSection.tsx` | Gallery cards editor |
+| `frontend/src/components/ElementSettings/GallerySettingsSectionCompact.tsx` | Gallery (compact) |
+| `frontend/src/components/ElementSettings/CarouselSettingsSection.tsx` | Carousel slides editor |
+| `frontend/src/components/ElementSettings/CarouselSettingsSectionCompact.tsx` | Carousel (compact) |
+| `frontend/src/components/ElementSettings/GalleryCarouselSettingsSectionCompact.tsx` | Gallery carousel nav settings (compact) |
+| `frontend/src/components/ElementSettings/GallerySectionStyleInputs.tsx` | Gallery section styling (header, title, spans, cards) with text alignment support |
+| `frontend/src/components/ElementSettings/InfoPanelSettingsSection.tsx` | Info panel sections editor (full-width) |
+| `frontend/src/components/ElementSettings/InfoPanelSettingsSectionCompact.tsx` | Info panel sections editor (compact for constructor sidebar) |
+| `frontend/src/components/ElementSettings/InfoPanelStyleInputs.tsx` | Info panel section styling (panel wrapper, image detail panel) |
+
+### Migrations
+
+| File | Purpose |
+|------|---------|
+| `20260326000001-rename-ui-elements-to-element-type-defaults.js` | Rename table |
+| `20260326000002-convert-element-type-enum-to-text.js` | ENUM to TEXT |
+| `20260326000003-create-project-element-defaults.js` | Create project scope table |
+| `20260326000004-backfill-project-element-defaults.js` | Backfill existing projects |
+
+## Known Considerations
+
+### 1. Virtual is_active Field
+
+**Issue:** `element_type_defaults.is_active` always returns `true` (virtual field). It's not actually stored or used.
+
+**Impact:** The "Active" checkbox in the admin UI has no real effect on element availability.
+
+### 2. Auto-Snapshot on Project Creation
+
+**Behavior:** When a project is created, all global defaults are automatically snapshotted to `project_element_defaults`.
+
+**Impact:** Projects start with a frozen copy of global defaults at creation time. Changes to global defaults don't affect existing projects unless manually reset via `/api/project-element-defaults/:id/reset`.
+
+### 3. Existing Projects Without Snapshots
+
+**Issue:** Projects created before the snapshot mechanism was added won't have `project_element_defaults` records.
+
+**Impact:** Constructor will load an empty `uiElementDefaultsByType` map, falling back to hardcoded defaults.
+
+**Mitigation:**
+- Migration `20260326000004-backfill-project-element-defaults.js` backfills existing projects
+- Migration `20260326171017-add-missing-element-type-defaults.js` adds spot, logo, popup types
+- Constructor handles empty defaults gracefully
+
+### 4. Field Name Aliasing
+
+**Issue:** Different tables use different field names for the same data:
+- `element_type_defaults`: `default_settings_json` (alias for `settings_json` in DB)
+- `project_element_defaults`: `settings_json` (direct)
+
+**Mitigation:** The `normalizeElementDefault()` utility in `types/constructor.ts` handles both:
+```typescript
+const rawSettings = row.settings_json ?? row.default_settings_json;
+```
+
+### 5. TEXT vs ENUM for element_type
+
+**Design Decision:** `element_type` uses TEXT everywhere instead of ENUM.
+
+**Benefits:**
+- New element types can be added without database migrations
+- Consistent across all three tiers
+- Application-level validation ensures type safety
+
+## Font Handling
+
+### Font Key System
+
+Font family properties use font **keys** rather than CSS `font-family` values. This allows distinguishing between font variants that share the same family name but differ in other properties (e.g., `fontStretch` for condensed variants).
+
+**File:** `frontend/src/lib/fonts.ts`
+
+```typescript
+// Font keys are unique identifiers
+const FONT_OPTIONS = [
+  { key: 'instrument-sans', fontFamily: 'Instrument Sans', label: 'Instrument Sans' },
+  { key: 'instrument-sans-condensed', fontFamily: 'Instrument Sans', fontStretch: 'condensed', label: 'Instrument Sans Condensed' },
+  // ...
+];
+
+// Resolve font key to full CSS style
+function getFontByKey(key: string): FontOption | undefined;
+function getFontStyle(font: FontOption): CSSProperties;
+```
+
+### Element Font Properties
+
+| Element Type | Font Properties |
+|--------------|-----------------|
+| Navigation | `navLabelFontFamily` |
+| Description | `descriptionTitleFontFamily`, `descriptionTextFontFamily` |
+| Gallery | `galleryTitleFontFamily`, `galleryTextFontFamily` |
+| Carousel | `carouselCaptionFontFamily` |
+| Info Panel | `infoPanelTriggerFontFamily`, `infoPanelHeaderFontFamily`, `panelTitleFontFamily`, `panelTextFontFamily`, `infoPanelSpanFontFamily`, `infoPanelCardTitleFontFamily`, `detailCaptionFontFamily` |
+
+### Font Resolution Pattern
+
+Element rendering components resolve font keys to CSS styles using `useMemo`:
+
+```typescript
+import { getFontByKey, getFontStyle } from '../../../lib/fonts';
+
+const labelFontStyle = useMemo(() => {
+  const fontKey = element.navLabelFontFamily;
+  if (!fontKey) return {};
+  const font = getFontByKey(fontKey);
+  return font ? getFontStyle(font) : { fontFamily: fontKey };
+}, [element.navLabelFontFamily]);
+
+// Applied to text elements
+<span style={labelFontStyle}>{element.navLabel}</span>
+```
+
+### Settings Component Pattern
+
+Font selectors use `font.key` as the option value:
+
+```typescript
+import { FONT_OPTIONS } from '../../lib/fonts';
+
+<select value={navLabelFontFamily} onChange={...}>
+  <option value=''>Not set</option>
+  {FONT_OPTIONS.map((font) => (
+    <option key={font.key} value={font.key}>
+      {font.label}
+    </option>
+  ))}
+</select>
+```
+
+## Security
+
+### Permissions
+
+Element defaults use `element_type_defaults` and `project_element_defaults` permissions. Page elements are managed through `tour_pages` permissions.
+
+| Permission | Operations |
+|------------|------------|
+| READ_ELEMENT_TYPE_DEFAULTS | List, view global defaults |
+| UPDATE_ELEMENT_TYPE_DEFAULTS | Edit global defaults (admin) |
+| READ_PROJECT_ELEMENT_DEFAULTS | List, view project defaults |
+| UPDATE_PROJECT_ELEMENT_DEFAULTS | Edit project defaults |
+| READ_TOUR_PAGES | View pages (includes elements in ui_schema_json) |
+| UPDATE_TOUR_PAGES | Edit pages (includes elements in ui_schema_json) |
+
+### Validation
+
+**Global scope (element_type_defaults):**
+- `element_type`: Required, unique, 1-100 chars
+- `name`: Required, 1-255 chars
+
+**Project scope (project_element_defaults):**
+- `projectId`: Required FK (validated by Sequelize)
+- `element_type`: Required, 1-100 chars
+- Unique constraint: `(projectId, element_type)`
+
+**Page elements (in ui_schema_json):**
+- Validated at application level in constructor
+- `type`: Required, must be a valid element type
+- Position values (xPercent, yPercent): 0-100 range
diff --git a/documentation/user-management.md b/documentation/user-management.md
new file mode 100644
index 0000000..dade3db
--- /dev/null
+++ b/documentation/user-management.md
@@ -0,0 +1,843 @@
+# User Management
+
+Complete documentation for the Tour Builder Platform's user management system including CRUD operations, invitations, bulk CSV import, and user profiles.
+
+## Overview
+
+The platform implements a comprehensive user management system with:
+- **CRUD Operations** - Create, read, update, delete users with role-based permissions
+- **Invitations** - Email-based invitation system with password setup tokens
+- **Bulk CSV Import** - Mass user creation from CSV files
+- **User Profiles** - Profile management with avatar support
+- **Password Management** - Password updates, resets, and email verification
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      User Management Flow                                │
+│                                                                          │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                 │
+│  │  Frontend   │    │   Backend   │    │  Database   │                 │
+│  │   Pages     │───▶│   Service   │───▶│   Models    │                 │
+│  └─────────────┘    └─────────────┘    └─────────────┘                 │
+│        │                  │                   │                         │
+│        │ Redux Store      │ UsersService      │ users table            │
+│        ▼                  ▼                   ▼                         │
+│   usersSlice.ts     users.js            users.js model                 │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      Invitation Flow                                     │
+│                                                                          │
+│  Create User ──▶ Generate Token ──▶ Send Email ──▶ User Sets Password  │
+│       │               │                  │                │             │
+│       ▼               ▼                  ▼                ▼             │
+│  UsersService   passwordResetToken  EmailSender    /password-reset     │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## User Database Model
+
+### Schema
+
+**File:** `backend/src/db/models/users.js`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| id | UUID | Yes | Auto | Primary key (UUIDv4) |
+| firstName | TEXT | No | null | User's first name |
+| lastName | TEXT | No | null | User's last name |
+| phoneNumber | TEXT | No | null | Phone number |
+| email | TEXT | Yes | - | Email (unique, validated) |
+| password | TEXT | Yes | - | bcrypt hashed password |
+| disabled | BOOLEAN | Yes | false | Account disabled status |
+| emailVerified | BOOLEAN | Yes | false | Email verification status |
+| emailVerificationToken | TEXT | No | null | Token for email verification |
+| emailVerificationTokenExpiresAt | DATE | No | null | Token expiration |
+| passwordResetToken | TEXT | No | null | Token for password reset |
+| passwordResetTokenExpiresAt | DATE | No | null | Token expiration |
+| provider | TEXT | Yes | 'local' | Auth provider (local, google, microsoft) |
+| importHash | VARCHAR(255) | No | null | Unique hash for bulk imports |
+| app_roleId | UUID | No | null | FK to roles table |
+| createdById | UUID | No | null | Audit: creator user |
+| updatedById | UUID | No | null | Audit: last updater |
+| createdAt | TIMESTAMP | Yes | Auto | Creation timestamp |
+| updatedAt | TIMESTAMP | Yes | Auto | Update timestamp |
+| deletedAt | TIMESTAMP | No | null | Soft delete timestamp |
+
+**Indexes:**
+- `email` - Unique index
+- `app_roleId` - FK index
+- `deletedAt` - Soft delete queries
+
+**Unique Constraints:**
+- `importHash` - Unique constraint on column (for bulk import deduplication)
+
+### Relationships
+
+```
+users
+├── belongsTo roles (as app_role) ─────────────────── SET NULL on delete
+├── belongsToMany permissions (as custom_permissions) ── CASCADE on delete
+├── hasMany file (as avatar) ──────────────────────── CASCADE on delete
+├── hasMany project_memberships ───────────────────── CASCADE on delete
+├── hasMany presigned_url_requests ────────────────── CASCADE on delete
+├── hasMany publish_events ────────────────────────── SET NULL on delete
+├── hasMany access_logs ───────────────────────────── SET NULL on delete
+├── belongsTo users (as createdBy) ────────────────── Audit trail
+└── belongsTo users (as updatedBy) ────────────────── Audit trail
+```
+
+### Model Hooks
+
+**beforeCreate:**
+```javascript
+// Trim string fields
+users.email = users.email.trim();
+users.firstName = users.firstName?.trim() || null;
+users.lastName = users.lastName?.trim() || null;
+
+// For OAuth users (non-LOCAL provider) that are valid providers:
+if (users.provider !== providers.LOCAL && Object.values(providers).indexOf(users.provider) > -1) {
+  users.emailVerified = true;  // Auto-verify OAuth emails
+  if (!users.password) {
+    // Generate random password if not provided
+    const password = crypto.randomBytes(20).toString('hex');
+    users.password = bcrypt.hashSync(password, config.bcrypt.saltRounds);
+  }
+}
+```
+
+**Note:** Provider values are lowercase strings: `'local'`, `'google'`, `'microsoft'` (stored as `providers.LOCAL`, etc. from config).
+
+## CRUD Operations
+
+### Create User
+
+**Endpoint:** `POST /api/users`
+
+**Permission:** `CREATE_USERS`
+
+**Request Body:**
+```json
+{
+  "data": {
+    "email": "user@example.com",
+    "firstName": "John",
+    "lastName": "Doe",
+    "phoneNumber": "+1-555-1234",
+    "disabled": false,
+    "password": "optional-initial-password",
+    "app_role": "role-uuid",
+    "custom_permissions": ["perm-uuid-1", "perm-uuid-2"],
+    "avatar": [{ "id": "file-uuid" }]
+  }
+}
+```
+
+**Response:** `true` on success
+
+**Service Logic:**
+
+```javascript
+// 1. Check if email already exists
+let user = await db.users.findOne({ where: { email }, paranoid: false, transaction });
+if (user && !user.deletedAt) {
+  throw new ValidationError('iam.errors.userAlreadyExists');
+}
+
+// 2. Create or restore user record
+if (user?.deletedAt) {
+  await user.restore({ transaction });
+  await UsersDBApi.update({ id: user.id, data, currentUser, transaction });
+} else {
+  await UsersDBApi.create({ data, currentUser, transaction });
+}
+
+// 3. Replace private production presentation grants for Public users
+// 4. Send invitation email (if enabled)
+AuthService.sendPasswordResetEmail(email, 'invitation', host);
+```
+
+If a user was soft-deleted, PostgreSQL still enforces the unique `users.email`
+constraint. Creating a user with that email restores and updates the soft-deleted
+record instead of inserting a duplicate row.
+
+**Default Values Applied:**
+- `disabled`: false
+- `emailVerified`: true (for admin-created users)
+- `app_role`: "User" role if not specified
+- `provider`: `local`
+- `password`: generated temporary password when not supplied, stored as bcrypt
+  hash; invitation flow then sends a password-reset link
+
+### Read Users
+
+**List Users:**
+```http
+GET /api/users?page=1&limit=10&field=createdAt&sort=desc
+Authorization: Bearer {token}
+```
+
+**Filters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| firstName | string | Case-insensitive search |
+| lastName | string | Case-insensitive search |
+| phoneNumber | string | Case-insensitive search |
+| email | string | Case-insensitive search |
+| disabled | boolean | Exact match |
+| emailVerified | boolean | Exact match |
+| provider | string | Case-insensitive search |
+| app_role | string | Role ID or name (pipe-separated for multiple) |
+| custom_permissions | string | Permission ID or name (pipe-separated) |
+| createdAtRange | array | `[startDate, endDate]` |
+
+**Response:**
+```json
+{
+  "rows": [
+    {
+      "id": "uuid",
+      "firstName": "John",
+      "lastName": "Doe",
+      "email": "john@example.com",
+      "disabled": false,
+      "emailVerified": true,
+      "provider": "LOCAL",
+      "app_role": { "id": "uuid", "name": "User" },
+      "custom_permissions": [],
+      "avatar": [{ "id": "uuid", "publicUrl": "..." }],
+      "createdAt": "2025-01-01T00:00:00Z"
+    }
+  ],
+  "count": 100
+}
+```
+
+**Single User:**
+```http
+GET /api/users/{id}
+Authorization: Bearer {token}
+```
+
+**Note:** Password field is explicitly removed from response.
+
+**Autocomplete:**
+```http
+GET /api/users/autocomplete?query=john&limit=10&offset=0
+Authorization: Bearer {token}
+```
+
+Returns `[{ id: "uuid", label: "John" }]` format.
+
+**Count:**
+```http
+GET /api/users/count
+Authorization: Bearer {token}
+```
+
+**CSV Export:**
+```http
+GET /api/users?filetype=csv
+Authorization: Bearer {token}
+```
+
+Returns CSV with columns: `id`, `firstName`, `lastName`, `phoneNumber`, `email`
+
+### Update User
+
+**Endpoint:** `PUT /api/users/{id}`
+
+**Permission:** `UPDATE_USERS`
+
+**Request Body:**
+```json
+{
+  "id": "user-uuid",
+  "data": {
+    "firstName": "Updated Name",
+    "password": "new-password",
+    "app_role": "new-role-uuid",
+    "custom_permissions": ["perm-uuid"],
+    "avatar": [{ "id": "file-uuid" }]
+  }
+}
+```
+
+**Password Handling:**
+- If password provided: Hashed with bcrypt before storing
+- If not provided: Existing password preserved
+
+**emailVerified Behavior:**
+- If not specified in update: Defaults to `true`
+- Can be explicitly set to `false` if needed
+
+### Delete User
+
+**Single Delete:**
+```http
+DELETE /api/users/{id}
+Authorization: Bearer {token}
+```
+
+**Validations:**
+- Cannot delete yourself: `iam.errors.deletingHimself`
+- Must have Administrator role: `errors.forbidden.message`
+
+**Bulk Delete:**
+```http
+POST /api/users/deleteByIds
+Authorization: Bearer {token}
+
+{
+  "data": ["user-uuid-1", "user-uuid-2"]
+}
+```
+
+**Note:** Uses soft delete (sets `deletedAt` timestamp).
+
+**Bulk delete:** Handled by the factory-generated `UsersService.deleteByIds({ ids, currentUser, runtimeContext })` method and delegated to `UsersDBApi.deleteByIds({ ids, currentUser, transaction, runtimeContext })`.
+
+## Invitation System
+
+### How Invitations Work
+
+1. Admin creates a user via UI or API
+2. System generates a password reset token
+3. Invitation email sent with setup link
+4. User clicks link and sets their password
+5. Account is activated
+
+### Token Generation
+
+**File:** `backend/src/db/api/users.js`
+
+```javascript
+static async generatePasswordResetToken(email, options) {
+  const token = crypto.randomBytes(20).toString('hex');  // 40-char hex
+  const TOKEN_EXPIRY_MS = 24 * 60 * 60 * 1000;  // 24 hours
+  const tokenExpiresAt = Date.now() + TOKEN_EXPIRY_MS;
+
+  await users.update({
+    passwordResetToken: token,
+    passwordResetTokenExpiresAt: tokenExpiresAt,
+  });
+
+  return token;
+}
+```
+
+**Token Properties:**
+| Property | Value |
+|----------|-------|
+| Format | 40-character hexadecimal |
+| Expiration | 24 hours |
+| Storage | `passwordResetToken` field |
+| Reusable | Yes (token NOT cleared after use - see Known Issues) |
+
+### Invitation Email
+
+**Email Service:** `backend/src/services/email/list/invitation.js`
+
+**Template:** `backend/src/services/email/htmlTemplates/invitation/invitationTemplate.html`
+
+**Email Content:**
+- Subject: Invitation to join the platform
+- Body: Welcome message with "Set up account" button
+- Link: `{host}/password-reset?token={token}&invitation=true`
+
+**Template Variables:**
+| Variable | Description |
+|----------|-------------|
+| `{appTitle}` | Application name |
+| `{signupUrl}` | Password reset URL with token |
+| `{to}` | Recipient email address |
+
+### Sending Invitations
+
+```javascript
+// Called from UsersService.create()
+AuthService.sendPasswordResetEmail(email, 'invitation', host);
+```
+
+**Email Service Configuration:**
+```javascript
+// backend/src/config.ts
+email: {
+  from: 'Tour Builder Platform <app@flatlogic.app>',
+  host: 'email-smtp.us-east-1.amazonaws.com',
+  port: 587,
+  auth: {
+    user: process.env.EMAIL_USER,
+    pass: process.env.EMAIL_PASS,
+  }
+}
+```
+
+**Note:** If email is not configured (`EmailSender.isConfigured` returns false), invitations are silently skipped.
+
+## Bulk CSV Import
+
+### Endpoint
+
+```http
+POST /api/users/bulk-import
+Content-Type: multipart/form-data
+Authorization: Bearer {token}
+```
+
+**Permission:** `CREATE_USERS`
+
+### CSV Format
+
+**Required Fields:**
+- `email` - Must be present in every row
+
+**Optional Fields:**
+- `firstName`
+- `lastName`
+- `phoneNumber`
+- `disabled` (true/false)
+- `password`
+- `provider`
+
+**Example CSV:**
+```csv
+firstName,lastName,email,phoneNumber,disabled
+John,Doe,john@example.com,555-1234,false
+Jane,Smith,jane@example.com,555-5678,false
+Alice,Johnson,alice@example.com,555-9012,false
+```
+
+### Import Process
+
+**File:** `backend/src/services/users.ts`
+
+```javascript
+static async bulkImport(req, res, sendInvitationEmails = true, host) {
+  // 1. Parse CSV file
+  await processFile(req, res);
+  const bufferStream = new stream.PassThrough();
+  bufferStream.end(Buffer.from(req.file.buffer, "utf-8"));
+
+  const results = [];
+  await new Promise((resolve, reject) => {
+    bufferStream
+      .pipe(csv())
+      .on('data', (data) => results.push(data))
+      .on('end', () => resolve())
+      .on('error', (error) => reject(error));
+  });
+
+  // 2. Validate all rows have email
+  const hasAllEmails = results.every((result) => result.email);
+  if (!hasAllEmails) {
+    throw new ValidationError('importer.errors.userEmailMissing');
+  }
+
+  // 3. Bulk create users
+  await UsersDBApi.bulkImport(results, { transaction, currentUser });
+
+  // 4. Send invitation emails
+  emailsToInvite.forEach((email) => {
+    AuthService.sendPasswordResetEmail(email, 'invitation', host);
+  });
+}
+```
+
+### Bulk Import Behavior
+
+| Aspect | Behavior |
+|--------|----------|
+| Default Role | "User" role assigned to all imported users |
+| emailVerified | `false` (unlike single create which defaults to `true`) |
+| Duplicate Handling | `ignoreDuplicates: true` - skips existing emails |
+| Transaction | All-or-nothing: rollback on any error |
+| Invitation Emails | Sent to all imported email addresses |
+
+**Known Issue:** The invitation email logic has inverted condition:
+```javascript
+// BUG: Emails only sent when sendInvitationEmails is FALSE
+if (emailsToInvite && emailsToInvite.length && !sendInvitationEmails) {
+  emailsToInvite.forEach((email) => {
+    AuthService.sendPasswordResetEmail(email, 'invitation', host);
+  });
+}
+```
+
+### Frontend CSV Import
+
+**Component:** Uses `DragDropFilePicker` in list page
+
+**Redux Action:**
+```typescript
+dispatch(uploadCsv(file));
+dispatch(setRefetch(true));  // Refresh table after import
+```
+
+**Download Existing Users as CSV:**
+```typescript
+// Button click handler
+window.open('/api/users?filetype=csv', '_blank');
+```
+
+## User Profiles
+
+### Profile Update Endpoint
+
+```http
+PUT /api/auth/profile
+Authorization: Bearer {token}
+
+{
+  "firstName": "John",
+  "lastName": "Doe",
+  "phoneNumber": "+1-555-1234",
+  "avatar": [{ "id": "file-uuid" }]
+}
+```
+
+**Service:** `AuthService.updateProfile(profile, currentUser)`
+
+### Updatable Profile Fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| firstName | string | Trimmed on save |
+| lastName | string | Trimmed on save |
+| phoneNumber | string | No validation |
+| email | string | Can be changed |
+| avatar | file[] | Via FileDBApi |
+
+### Avatar Handling
+
+**Storage Configuration:**
+```javascript
+{
+  belongsTo: 'users',
+  belongsToColumn: 'avatar',
+  belongsToId: users.id
+}
+```
+
+**File Upload:**
+- Uses chunked upload system (see Asset Upload documentation)
+- Path scoped to `users/avatar`
+- Stored in `file` table with FK to user
+
+**Frontend Component:** `FormImagePicker` with `path='users/avatar'`
+
+## Password Management
+
+### Password Update (Authenticated)
+
+```http
+PUT /api/auth/password-update
+Authorization: Bearer {token}
+
+{
+  "currentPassword": "old-password",
+  "newPassword": "new-password"
+}
+```
+
+**Validations:**
+- Current password must match stored hash
+- New password cannot be same as current password
+
+**Errors:**
+| Error Code | Description |
+|------------|-------------|
+| `auth.wrongPassword` | Current password incorrect |
+| `auth.passwordUpdate.samePassword` | New password same as current |
+
+### Password Reset (Forgot Password)
+
+**Step 1: Request Reset Email**
+```http
+POST /api/auth/send-password-reset-email
+
+{ "email": "user@example.com" }
+```
+
+**Rate Limit:** 5 requests per hour per IP
+
+**Step 2: Reset Password**
+```http
+PUT /api/auth/password-reset
+
+{
+  "token": "40-char-hex-token",
+  "password": "new-password"
+}
+```
+
+**Token Validation:**
+- Must exist in database
+- Must not be expired (`passwordResetTokenExpiresAt > Date.now()`)
+
+**Error:** `auth.passwordReset.invalidToken`
+
+### Password Hashing
+
+**Algorithm:** bcrypt
+
+**Configuration:**
+```javascript
+// backend/src/config.ts
+bcrypt: {
+  saltRounds: 12
+}
+```
+
+**Applied In:**
+- User model `beforeCreate` hook
+- `UsersDBApi.update()` when password field present
+- `UsersDBApi.updatePassword()`
+- Password reset/setup flow
+
+## Email Verification
+
+### Generate Verification Token
+
+```javascript
+UsersDBApi.generateEmailVerificationToken(email);
+```
+
+Same format as password reset token: 40-char hex, 24-hour expiration.
+
+### Verify Email
+
+```http
+PUT /api/auth/verify-email
+
+{ "token": "verification-token" }
+```
+
+**Process:**
+1. Find user by `emailVerificationToken`
+2. Check `emailVerificationTokenExpiresAt > Date.now()`
+3. Set `emailVerified = true`
+4. Clear verification token
+
+### Request Verification Email
+
+```http
+POST /api/auth/send-email-address-verification-email
+Authorization: Bearer {token}
+```
+
+Sends email with verification link to current user's email.
+
+## Role & Permission Assignment
+
+### Default Role Assignment
+
+**Single User Creation:**
+```javascript
+if (!data.app_role) {
+  const role = await db.roles.findOne({ where: { name: 'User' } });
+  if (role) {
+    await users.setApp_role(role);
+  }
+} else {
+  await users.setApp_role(data.app_role);
+}
+```
+
+**Bulk Import:**
+All users receive "User" role (no per-user role in CSV).
+
+**Self-Registration:**
+
+Self-registration is disabled. New users are created by Administrator, Platform
+Owner, or Account Manager through the Users flow, with the role selected in the
+user form.
+
+### Custom Permissions
+
+Users can have additional permissions beyond their role:
+
+```javascript
+// Assign custom permissions
+await users.setCustom_permissions(permissionIds);
+```
+
+**Junction Table:** `usersCustom_permissionsPermissions`
+
+**Permission Resolution:**
+```javascript
+// User's effective permissions = role.permissions + custom_permissions
+const permissions = new Set([
+  ...(user.app_role?.permissions || []),
+  ...(user.custom_permissions || [])
+]);
+```
+
+## API Reference
+
+### Endpoints Summary
+
+| Method | Endpoint | Permission | Description |
+|--------|----------|------------|-------------|
+| POST | `/api/users` | CREATE_USERS | Create user |
+| POST | `/api/users/bulk-import` | CREATE_USERS | Bulk import CSV |
+| GET | `/api/users` | READ_USERS | List users |
+| GET | `/api/users/count` | READ_USERS | Count users |
+| GET | `/api/users/autocomplete` | READ_USERS | Autocomplete search |
+| GET | `/api/users/{id}` | READ_USERS | Get single user |
+| PUT | `/api/users/{id}` | UPDATE_USERS | Update user |
+| DELETE | `/api/users/{id}` | DELETE_USERS + Admin role | Delete user (see note) |
+| POST | `/api/users/deleteByIds` | CREATE_USERS | Bulk delete (POST → CREATE) |
+| PUT | `/api/auth/profile` | Authenticated | Update own profile |
+| PUT | `/api/auth/password-update` | Authenticated | Change password |
+| POST | `/api/auth/send-password-reset-email` | Public (rate limited) | Request reset |
+| PUT | `/api/auth/password-reset` | Public | Reset password |
+| PUT | `/api/auth/verify-email` | Public | Verify email |
+
+**Note on DELETE:** Single user delete requires BOTH:
+1. `DELETE_USERS` permission (via `checkCrudPermissions` middleware)
+2. `Administrator` role name check (in `UsersService.remove()`)
+
+**Self-Access Bypass:** Users can access their own resources via GET/PUT without specific permissions if their user ID matches the resource ID.
+
+### Permission Middleware
+
+All `/api/users` routes use:
+```javascript
+router.use(checkCrudPermissions('users'));
+```
+
+This applies:
+- `CREATE_USERS` for POST
+- `READ_USERS` for GET
+- `UPDATE_USERS` for PUT
+- `DELETE_USERS` for DELETE
+
+## Frontend Implementation
+
+### Redux Store
+
+**File:** `frontend/src/stores/users/usersSlice.ts`
+
+**Actions:**
+| Action | Description |
+|--------|-------------|
+| `fetch({ id, query })` | Get single user or list |
+| `create(data)` | Create new user |
+| `update({ id, data })` | Update user |
+| `deleteItem(id)` | Delete single user |
+| `deleteItemsByIds(ids)` | Bulk delete |
+| `uploadCsv(file)` | Import CSV |
+| `setRefetch(true)` | Trigger table refresh |
+
+### Pages
+
+**Location:** `frontend/src/pages/users/`
+
+| Page | File | Description |
+|------|------|-------------|
+| List | `users-list.tsx` (29 LOC) | User list with search, CSV import (factory-generated) |
+| Table | `users-table.tsx` (168 LOC) | Alternative table view (manual implementation) |
+| New | `users-new.tsx` (155 LOC) | Create user form |
+| Edit (query) | `users-edit.tsx` (168 LOC) | Edit user form (query param), including Public user private presentation grants |
+| Edit (path) | `[usersId].tsx` (197 LOC) | Edit user form (path param) |
+| View | `users-view.tsx` (524 LOC) | Read-only user details |
+
+**Note:** Two edit routes exist - query-based (`?id=`) and dynamic path-based (`[usersId].tsx`).
+
+### Table Configuration
+
+**Components:** `frontend/src/components/Users/`
+- `TableUsers.tsx` - Data grid component (23 LOC)
+- `CardUsers.tsx` - Card view component (194 LOC)
+- `ListUsers.tsx` - List view component (145 LOC)
+- `configureUsersCols.tsx` - Column definitions with permission-based editability (63 LOC)
+
+**Columns:**
+| Column | Type | Editable |
+|--------|------|----------|
+| firstName | text | Yes |
+| lastName | text | Yes |
+| phoneNumber | text | Yes |
+| email | text | Yes |
+| disabled | boolean toggle | Yes |
+| avatar | image | No |
+| app_role | select dropdown | Yes |
+| custom_permissions | multi-select | No |
+| actions | icons | - |
+
+## File Reference
+
+### Backend Files
+
+| File | LOC | Purpose |
+|------|-----|---------|
+| `backend/src/db/models/users.js` | 230 | User model definition |
+| `backend/src/db/api/users.js` | 734 | User database operations |
+| `backend/src/services/users.ts` | ~350 | User business logic |
+| `backend/src/routes/users.ts` | 64 | User API routes |
+| `backend/src/services/auth.ts` | - | Authentication & invitations |
+| `backend/src/services/email/list/invitation.js` | - | Invitation email |
+| `backend/src/services/email/htmlTemplates/invitation/` | - | Email template |
+
+### Frontend Files
+
+| File | LOC | Purpose |
+|------|-----|---------|
+| `frontend/src/stores/users/usersSlice.ts` | 25 | User Redux store |
+| `frontend/src/pages/users/` | 1241 | User management pages (6 files) |
+| `frontend/src/components/Users/` | 425 | User UI components (4 files) |
+
+## Known Issues
+
+### 1. emailVerified Default Inconsistency
+
+**Issue:** Single user create defaults `emailVerified` to `true`, but bulk import defaults to `false`.
+
+**Impact:** Bulk imported users may not be able to login if email verification is required.
+
+### 2. Password Reset Token Not Cleared After Use
+
+**Issue:** The `passwordResetToken` is not cleared from the database after a successful password reset.
+
+**Location:** `backend/src/services/auth.ts` and `backend/src/db/api/users.js`
+
+**Impact:** The same password reset token can be reused multiple times within the 24-hour expiration window to reset the user's password again.
+
+**Security Risk:** If a reset link is compromised, an attacker could reset the password multiple times.
+
+**Fix:** Clear the `passwordResetToken` and `passwordResetTokenExpiresAt` fields in `UsersDBApi.updatePassword()` or in `AuthService.passwordReset()` after successful password update.
+
+## Troubleshooting
+
+### User Cannot Login
+
+1. Check `disabled` is `false`
+2. Check `emailVerified` is `true` (or email service not configured)
+3. Verify password hash is set correctly
+4. Check `provider` matches login method (LOCAL vs OAuth)
+
+### Invitation Email Not Received
+
+1. Verify email service is configured (`EmailSender.isConfigured`)
+2. Check spam/junk folder
+3. Verify SMTP credentials in `.env`
+4. Check backend logs for email sending errors
+
+### Bulk Import Fails
+
+1. Ensure CSV has `email` column for all rows
+2. Check for duplicate emails (will be skipped)
+3. Verify CSV encoding (UTF-8 recommended)
+4. Check file size limits
+
+### Password Reset Token Invalid
+
+1. Token may be expired (24-hour limit)
+2. Token doesn't exist in database
+3. Check for URL encoding issues in token
+
+**Note:** Due to Known Issue #4, tokens are NOT cleared after use and can be reused within the expiration window.
diff --git a/documentation/video-playback.md b/documentation/video-playback.md
new file mode 100644
index 0000000..308cf4d
--- /dev/null
+++ b/documentation/video-playback.md
@@ -0,0 +1,1077 @@
+# Video Playback Feature - E2E Documentation
+
+## Overview
+
+The Tour Builder Platform implements a comprehensive video playback system supporting forward and reverse playback modes. The system handles background videos, video player elements, and transition animations between pages in both Constructor (editing) and Runtime (presentation) modes.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Video Types                                 │
+│  Background Videos │ Video Player Elements │ Transition Videos  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Playback Hooks                               │
+│  useTransitionPlayback │ useReversePlayback │ usePageSwitch     │
+│  useBackgroundVideoPlayback (background video time control)      │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Preloading Layer                             │
+│  usePreloadOrchestrator │ getReadyBlobUrl (O(1)) │ S3 Presign  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Utilities                                    │
+│  mediaDuration.ts │ assetUrl.ts │ StorageManager (Cache API)   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Rendering                                    │
+│  Constructor Page │ RuntimePresentation │ Transition Overlay    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Video Types
+
+### 1. Background Videos
+
+Full-screen videos that play behind page content with configurable playback settings.
+
+```tsx
+// Using useBackgroundVideoPlayback hook for custom time control
+const { videoRef, shouldBlockAutoplay } = useBackgroundVideoPlayback({
+  videoUrl: page.background_video_url,
+  autoplay: page.background_video_autoplay ?? true,
+  loop: page.background_video_loop ?? true,
+  muted: page.background_video_muted ?? true,
+  startTime: page.background_video_start_time ?? null,
+  endTime: page.background_video_end_time ?? null,
+});
+
+// Block autoplay if video already played this session (when loop=false)
+const effectiveAutoplay = (page.background_video_autoplay ?? true) && !shouldBlockAutoplay;
+
+<video
+  ref={videoRef}
+  src={page.background_video_url}
+  autoPlay={effectiveAutoplay}
+  loop={page.background_video_end_time == null ? (page.background_video_loop ?? true) : false}
+  muted={page.background_video_muted ?? true}
+  playsInline
+  className="absolute inset-0 w-full h-full object-cover"
+/>
+```
+
+**Configurable Properties (stored in `tour_pages`):**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `background_video_autoplay` | boolean | true | Start playback automatically |
+| `background_video_loop` | boolean | true | Loop continuously |
+| `background_video_muted` | boolean | true | Mute audio (required for autoplay policy) |
+| `background_video_start_time` | DECIMAL(10,1) \| null | null | Start playback at this time (seconds, 0.1s precision) |
+| `background_video_end_time` | DECIMAL(10,1) \| null | null | Stop/loop at this time (seconds, 0.1s precision) |
+
+**DECIMAL Parsing (Critical):** Sequelize DECIMAL fields return strings from the database (e.g., `"2.5"` not `2.5`). In runtime code, these must be parsed with `parseFloat(String(value))` before passing to the hook.
+
+**Note:** When `background_video_end_time` is set, native HTML5 `loop` attribute is disabled and looping is handled via JavaScript (`timeupdate` event) to properly seek back to `startTime`.
+
+**Session-Scoped Play Once Behavior (when loop=false):**
+When loop is disabled, videos only play once per browser session:
+1. Video plays normally on first navigation to the page
+2. When video ends, the video URL is added to a session-scoped Set (`playedVideos`)
+3. On subsequent visits within the same session, autoplay is blocked and video shows last frame
+4. Session tracking resets on browser refresh (module-level state, not persisted)
+
+#### Global Sound Control and Autoplay Compatibility
+
+Browsers block unmuted autoplay until the user interacts with the page. iOS WebKit is especially strict and can show native play overlays for unmuted videos. The platform handles this with a shared global mute state:
+
+**Problem:** unmuted background audio/video, hover/click effects, and media-player sound cannot reliably autoplay before user interaction.
+
+**Solution:**
+1. **CSS Layer** - Hide native iOS video controls via `-webkit-media-controls-*` selectors in `main.css`
+2. **Always Start Muted** - Presentation audio starts muted for autoplay compatibility
+3. **Global Sound Control** - `backgroundAudioController` stores shared mute state; `useGlobalAudioMute` exposes it to React
+4. **Custom Sound Button** - `useVideoSoundControl` drives the RuntimeControls sound button and decides when it should be visible
+5. **webkit-playsinline** - Legacy attribute added to `<video>` for older iOS versions
+
+```tsx
+// useVideoSoundControl hook usage in RuntimePresentation
+const soundControl = useVideoSoundControl({
+  pageHasSound: page.background_video_muted === false,
+  hasBackgroundVideo: Boolean(backgroundVideoUrl),
+  hasBackgroundAudio: Boolean(backgroundAudioUrl),
+  hasElementAudio,
+});
+
+// Background video follows global presentation mute state
+<video
+  muted={soundControl.isMuted}
+  playsInline
+  webkit-playsinline=""
+/>
+
+// Sound toggle button in RuntimeControls
+<RuntimeControls
+  showSoundButton={soundControl.showSoundButton}
+  isMuted={soundControl.isMuted}
+  onSoundToggle={soundControl.toggleSound}
+/>
+```
+
+**Key Behaviors:**
+| Behavior | Description |
+|----------|-------------|
+| Start muted | Presentation sound starts muted for browser autoplay compatibility |
+| Sound button | Appears when the page has background video sound, background audio, hover/click audio, media players, or gallery/info-panel videos |
+| Global scope | The same mute state controls background audio, background video, hover/click effects, audio/video player elements, and gallery/info-panel videos |
+| Fullscreen gallery | RuntimeControls are hidden while the fullscreen gallery is open, so gallery videos render a small sound button connected to the same global mute state |
+| User control | User can unmute via the sound button in RuntimeControls |
+| Event isolation | Unmuting does not replay already-active hover/click effects; sound effects only play on their own fresh `false -> true` hover/active transition |
+| UI chrome isolation | Runtime/global sound buttons stop event propagation so control clicks do not reach canvas or presentation elements |
+
+**Files Involved:**
+- `frontend/src/css/main.css` - CSS to hide native iOS controls
+- `frontend/src/lib/backgroundAudioController.ts` - Shared interaction, ducking, and mute state controller
+- `frontend/src/hooks/useGlobalAudioMute.ts` - React subscription hook for global mute state
+- `frontend/src/hooks/useVideoSoundControl.ts` - RuntimeControls sound-button visibility and actions
+- `frontend/src/components/Runtime/RuntimeControls.tsx` - Sound toggle button
+- `frontend/src/components/Constructor/CanvasBackground.tsx` - Background video/audio rendering with `webkit-playsinline`
+
+### 2. Video Player Elements
+
+Interactive video elements with controls, placed in page UI schema.
+
+```tsx
+// frontend/src/components/UiElements/elements/VideoPlayerElement.tsx
+<video
+  src={resolve(element.mediaUrl)}
+  controls
+  autoPlay={Boolean(element.mediaAutoplay)}
+  loop={Boolean(element.mediaLoop)}
+  muted={Boolean(element.mediaMuted)}
+  playsInline
+/>
+```
+
+**Configurable Properties:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `mediaUrl` | string | Video asset URL |
+| `mediaAutoplay` | boolean | Auto-start playback |
+| `mediaLoop` | boolean | Loop continuously |
+| `mediaMuted` | boolean | Mute audio |
+
+**Note:** Controls are always shown. The component uses `resolveAssetPlaybackUrl()` for URL resolution.
+
+### 3. Transition Videos
+
+Animated videos that play during page navigation.
+
+```typescript
+interface TransitionVideo {
+  video_url: string;        // Forward transition video
+  duration_sec: number;     // Duration in seconds
+  supports_reverse: boolean; // Can play in reverse
+}
+```
+
+---
+
+## Forward Playback
+
+### How It Works
+
+Forward playback uses native HTML5 video capabilities:
+
+```
+1. Set video.src = videoUrl
+2. Set video.autoPlay = true (or call video.play())
+3. Video plays from start to end
+4. 'ended' event fires → trigger next action
+```
+
+### Implementation
+
+```tsx
+// Transition overlay forward playback
+<video
+  ref={videoRef}
+  src={transitionVideoUrl}
+  autoPlay={!isReverse}
+  muted
+  playsInline
+  preload="auto"
+  onEnded={handleTransitionComplete}
+/>
+```
+
+### Fallback Timer
+
+If video fails to trigger `onEnded`, a fallback timer ensures navigation continues:
+
+```typescript
+const fallbackTimer = setTimeout(() => {
+  finishTransition();
+}, transitionDuration * 1000 + 500); // duration + buffer
+
+videoRef.current.onended = () => {
+  clearTimeout(fallbackTimer);
+  finishTransition();
+};
+```
+
+---
+
+## Reverse Playback
+
+### Overview
+
+Reverse playback is handled by `useReversePlayback` hook with two strategies:
+
+```
+┌─────────────────────┐
+│  Start Reverse      │
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐     Supported?     ┌─────────────────────┐
+│  Try Native Reverse │ ───────────────────│  Use Native         │
+│  (playbackRate=-1)  │        YES         │  playbackRate=-1    │
+└─────────┬───────────┘                    └─────────────────────┘
+          │ NO
+          ▼
+┌─────────────────────┐
+│  Frame-Stepping     │
+│  Fallback           │
+└─────────────────────┘
+```
+
+### Strategy 1: Native Reverse (Primary)
+
+Uses browser's native reverse playback when supported (Chrome, Edge):
+
+```typescript
+const startNativeReverse = () => {
+  video.currentTime = video.duration;
+  video.playbackRate = -1;
+  video.play();
+
+  video.ontimeupdate = () => {
+    if (video.currentTime <= 0.05) {
+      video.currentTime = 0;
+      onComplete();
+    }
+  };
+};
+```
+
+**Browser Support:**
+| Browser | Native Reverse |
+|---------|---------------|
+| Chrome | ✅ Supported |
+| Edge | ✅ Supported |
+| Firefox | ❌ Use fallback |
+| Safari | ❌ Use fallback |
+
+### Strategy 2: Frame-Stepping Fallback
+
+Manual frame-by-frame reverse for unsupported browsers:
+
+```typescript
+const startFrameStepping = () => {
+  const fps = isPreloaded ? 30 : 15;  // Adaptive FPS
+  const frameInterval = 1000 / fps;
+  const frameStep = 1 / fps;
+
+  let lastFrameTime = 0;
+
+  const stepFrame = (timestamp: number) => {
+    if (timestamp - lastFrameTime >= frameInterval) {
+      video.currentTime = Math.max(0, video.currentTime - frameStep);
+      lastFrameTime = timestamp;
+
+      if (video.currentTime <= 0) {
+        onComplete();
+        return;
+      }
+    }
+    requestAnimationFrame(stepFrame);
+  };
+
+  requestAnimationFrame(stepFrame);
+};
+```
+
+**Adaptive FPS:**
+| Condition | FPS | Reason |
+|-----------|-----|--------|
+| Preloaded video | 30 | Smooth playback, data available |
+| Streaming video | 15 | Conservative, bandwidth-aware |
+
+### Buffering Handling
+
+The system waits for sufficient buffered data before starting:
+
+```typescript
+const checkBuffered = () => {
+  const buffered = video.buffered;
+  if (buffered.length > 0) {
+    const bufferedEnd = buffered.end(buffered.length - 1);
+    const bufferedAmount = bufferedEnd - video.currentTime;
+
+    if (bufferedAmount >= 0.5) {  // 0.5 seconds minimum
+      startReverse();
+    }
+  }
+};
+```
+
+**Buffering Timeout:** 8 seconds before attempting with available buffer.
+
+### Hook API
+
+```typescript
+const {
+  startReverse,        // Start reverse playback (async)
+  stopReverse,         // Cancel reverse playback
+  isReversing,         // Currently playing in reverse
+  isBuffering,         // Waiting for buffer
+  canUseNativeReverse, // Browser supports playbackRate = -1
+} = useReversePlayback({
+  videoRef,
+  onComplete,
+  preloadedUrls?,      // Optional: Set of preloaded video URLs
+  videoUrl?,           // Optional: Current video URL for cache lookup
+  getCachedBlobUrl?,   // Optional: Function to get cached blob URL
+});
+```
+
+---
+
+## Constructor Mode
+
+### Video Preview System
+
+The Constructor provides comprehensive video testing:
+
+```typescript
+interface TransitionPreview {
+  videoUrl: string;           // Forward video URL
+  reverseVideoUrl?: string;   // Optional separate reverse video
+  reverseMode: 'reverse';     // Playback mode indicator
+}
+```
+
+### Video Loading Flow
+
+```
+1. User selects transition video
+2. Fetch video as blob (better seeking)
+3. Create blob URL
+4. Monitor readyState events
+5. Extract duration from metadata
+6. Enable preview controls
+```
+
+### Event Monitoring
+
+Constructor monitors comprehensive video events:
+
+```typescript
+// Ready state events
+video.addEventListener('loadedmetadata', handleMetadata);
+video.addEventListener('canplay', handleCanPlay);
+video.addEventListener('canplaythrough', handleReady);
+
+// Playback events
+video.addEventListener('playing', handlePlaying);
+video.addEventListener('ended', handleEnded);
+
+// Error events
+video.addEventListener('error', handleError);
+video.addEventListener('abort', handleAbort);
+video.addEventListener('stalled', handleStalled);
+```
+
+### Duration Extraction
+
+```typescript
+// frontend/src/lib/mediaDuration.ts (120 LOC)
+
+export interface MediaDurationResult {
+  duration: number;
+  width?: number;   // Only for video
+  height?: number;  // Only for video
+}
+
+export function probeMediaDuration(
+  source: string | File,          // URL string or File object
+  mediaType: 'video' | 'audio',   // Media type to probe
+  timeoutMs = 10000,              // Timeout in milliseconds
+): Promise<MediaDurationResult | null> {
+  return new Promise((resolve) => {
+    const mediaElement = mediaType === 'video'
+      ? document.createElement('video')
+      : document.createElement('audio');
+
+    mediaElement.preload = 'metadata';
+
+    mediaElement.onloadedmetadata = () => {
+      const result: MediaDurationResult = { duration: mediaElement.duration };
+      if (mediaType === 'video' && mediaElement instanceof HTMLVideoElement) {
+        result.width = mediaElement.videoWidth;
+        result.height = mediaElement.videoHeight;
+      }
+      cleanup();
+      resolve(result);
+    };
+
+    mediaElement.onerror = () => {
+      cleanup();
+      resolve(null);  // Returns null on error, not reject
+    };
+
+    // Source can be URL string or File object
+    mediaElement.src = typeof source === 'string'
+      ? source
+      : URL.createObjectURL(source);
+
+    setTimeout(() => {
+      cleanup();
+      resolve(null);
+    }, timeoutMs);
+  });
+}
+
+// Helper functions for MIME type detection
+export function isVideoMimeType(mimeType: string | null | undefined): boolean {
+  if (!mimeType) return false;
+  return mimeType.startsWith('video/');
+}
+
+export function isAudioMimeType(mimeType: string | null | undefined): boolean {
+  if (!mimeType) return false;
+  return mimeType.startsWith('audio/');
+}
+```
+
+### Preview Controls
+
+| Control | Forward Mode | Reverse Mode |
+|---------|-------------|--------------|
+| Play | Native play() | startReverse() |
+| Pause | Native pause() | stopReverse() |
+| Progress | timeupdate event | Manual tracking |
+
+---
+
+## Runtime Mode (Presentations)
+
+### RuntimePresentation Component
+
+Handles video playback during tour presentations:
+
+```tsx
+// frontend/src/components/RuntimePresentation.tsx
+
+// Background video rendering
+{page.background_video_url && (
+  <video
+    src={resolveAssetUrl(page.background_video_url)}
+    autoPlay
+    loop
+    muted
+    playsInline
+    className="absolute inset-0 w-full h-full object-cover -z-10"
+  />
+)}
+
+// Video player elements
+{element.type === 'video_player' && (
+  <video
+    src={resolveAssetUrl(element.content_json.mediaUrl)}
+    controls={element.content_json.mediaControls}
+    autoPlay={element.content_json.autoPlay}
+    loop={element.content_json.loop}
+    muted={element.content_json.muted}
+  />
+)}
+```
+
+### Transition Overlay Flow
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  1. User clicks navigation element                           │
+│     └── Resolve targetPageSlug → targetPageId                │
+│     └── startNavigation(targetPageId, element)               │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  2. Determine transition type                                │
+│     └── isReverse = isBack && linkData.supports_reverse      │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  3. Set overlay transition state                             │
+│     └── setOverlayTransition({ videoUrl, isReverse })        │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  4. Render transition overlay with video                     │
+│     └── <TransitionOverlay video={...} />                    │
+└──────────────────────────────────────────────────────────────┘
+                              │
+          ┌───────────────────┴───────────────────┐
+          │                                       │
+          ▼                                       ▼
+┌──────────────────────┐              ┌──────────────────────┐
+│  Forward Playback    │              │  Reverse Playback    │
+│  - autoPlay={true}   │              │  - useReversePlayback│
+│  - Wait for onEnded  │              │  - Wait for complete │
+└──────────┬───────────┘              └──────────┬───────────┘
+           │                                      │
+           └──────────────────┬───────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│  5. Finish transition                                        │
+│     └── finishOverlayTransition() → switch pages             │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Transition State Management
+
+The `useTransitionPlayback` hook manages transition video playback with comprehensive state tracking:
+
+```typescript
+// frontend/src/hooks/useTransitionPlayback.ts
+
+// Reverse playback modes
+export type ReverseMode = 'none' | 'reverse' | 'separate';
+
+// Transition configuration passed to the hook
+export interface TransitionConfig {
+  videoUrl: string;           // Forward transition video URL
+  storageKey?: string;        // Raw storage path for cache lookup
+  reverseMode: ReverseMode;   // How to handle reverse playback
+  reverseVideoUrl?: string;   // Separate reverse video (for 'separate' mode)
+  durationSec?: number;       // Expected duration in seconds
+  targetPageId?: string;      // Target page for navigation
+  displayName?: string;       // Human-readable name for logging
+}
+
+// Playback phases
+export type PlaybackPhase =
+  | 'idle'        // No transition active
+  | 'preparing'   // Loading video, resolving URLs
+  | 'playing'     // Forward playback in progress
+  | 'reversing'   // Reverse playback in progress
+  | 'finishing'   // Pre-decoding target page images
+  | 'completed';  // Transition finished, ready for page switch
+
+// Hook options
+export interface UseTransitionPlaybackOptions {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  transition: TransitionConfig | null;
+  onComplete: (targetPageId?: string) => void;
+  onError?: (reason: string) => void;
+
+  timeouts?: {
+    playbackStartMs?: number;   // Max wait for playback to start (default: 3000)
+    durationBufferMs?: number;  // Buffer after expected duration (default: 200)
+    hardTimeoutMs?: number;     // Absolute max timeout (default: 45000)
+  };
+  features?: {
+    useBlobUrl?: boolean;             // Force blob URL loading
+    preDecodeImages?: boolean;        // Pre-decode target page images
+    getTargetPageImages?: () => string[];  // Get images to pre-decode
+  };
+  preload?: {
+    preloadedUrls?: Set<string>;
+    getCachedBlobUrl?: (url: string) => Promise<string | null>;
+    getReadyBlobUrl?: (url: string) => string | null;
+  };
+}
+
+// Hook result
+export interface UseTransitionPlaybackResult {
+  phase: PlaybackPhase;       // Current playback phase
+  isBuffering: boolean;       // Waiting for video data
+  isReversing: boolean;       // Currently in reverse playback
+  cancel: () => void;         // Cancel transition immediately
+  forceComplete: () => void;  // Force transition to complete
+}
+```
+
+**Default Timeouts:**
+```typescript
+const DEFAULT_TIMEOUTS = {
+  playbackStartMs: 3000,   // 3 seconds to start playing
+  durationBufferMs: 200,   // 200ms buffer after expected end
+  hardTimeoutMs: 45000,    // 45 seconds absolute maximum
+};
+```
+
+**Usage Example:**
+```typescript
+const { phase, isBuffering, cancel, forceComplete } = useTransitionPlayback({
+  videoRef,
+  transition: {
+    videoUrl: resolveAssetPlaybackUrl(element.transitionVideoUrl),
+    storageKey: element.transitionVideoUrl,
+    reverseMode: isBack ? 'reverse' : 'none',
+    durationSec: element.transitionDurationSec,
+    targetPageId: targetPage.id,
+    displayName: element.label,
+  },
+  onComplete: (targetPageId) => {
+    setCurrentPageId(targetPageId);
+    setOverlayTransition(null);
+  },
+  onError: (reason) => {
+    console.error('Transition failed:', reason);
+    // Navigate anyway to prevent user being stuck
+    setCurrentPageId(targetPageId);
+    setOverlayTransition(null);
+  },
+  preload: {
+    getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,
+    getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+  },
+});
+```
+
+---
+
+## Video URL Resolution
+
+The `resolveAssetPlaybackUrl()` utility normalizes video URLs with presigned URL cache lookup:
+
+```typescript
+// frontend/src/lib/assetUrl.ts
+export const resolveAssetPlaybackUrl = (value?: string): string => {
+  const normalized = String(value || '').trim();
+  if (!normalized) return '';
+
+  // Pass through special URLs
+  if (normalized.startsWith('data:') || normalized.startsWith('blob:'))
+    return normalized;
+
+  // Already an API file download URL
+  if (normalized.startsWith('/api/file/download')) return normalized;
+
+  // File download path (prepend API base)
+  if (normalized.startsWith('/file/download'))
+    return `${baseURLApi}${normalized}`;
+
+  // Full URLs pass through
+  if (normalized.startsWith('http://') || normalized.startsWith('https://'))
+    return normalized;
+
+  // Relative path - check presigned URL cache first (for fast S3 access)
+  const presigned = getPresignedUrl(normalized);
+  if (presigned) {
+    return presigned;
+  }
+
+  // Fallback to backend proxy
+  const normalizedPrivateUrl = normalized.replace(/^\/+/, '');
+  return `${baseURLApi}/file/download?privateUrl=${encodeURIComponent(normalizedPrivateUrl)}`;
+};
+```
+
+**Presigned URL Priority:** The function first checks if a valid presigned S3 URL is cached for the storage key. If found and not expired, it returns the presigned URL for direct S3 access. Otherwise, it falls back to the backend proxy endpoint.
+
+---
+
+## Cache Integration
+
+### S3 Presigned URL Preloading
+
+Videos are preloaded directly from S3 using presigned URLs:
+
+```
+1. POST /api/file/presign { urls: [video1, video2, ...] }  // Max 50 per batch
+2. Download from S3 presigned URLs (1-hour expiry)
+3. Store in Cache API (dual key: download URL + storage key)
+4. Create blob URL: URL.createObjectURL(blob)
+5. Store in readyBlobUrlsRef Map (dual key: download URL + storage key) for O(1) instant lookup
+```
+
+**Storage Key Mapping:** Videos are cached by canonical storage key (e.g., `assets/project/transition.mp4`) in addition to download URLs. This ensures cache hits even when presigned URL signatures change between sessions.
+
+### Ready Blob URL Lookup (Primary)
+
+For instant video playback, use `getReadyBlobUrl()` which returns pre-created blob URLs. Lookups prioritize **storage key** over resolved URLs for reliable cache hits:
+
+```typescript
+// 1. Primary: O(1) lookup by storage key (most reliable)
+const readyUrl = preloadOrchestrator.getReadyBlobUrl(storageKey);
+if (readyUrl) {
+  video.src = readyUrl;  // Instant playback - no decode needed for video
+  return;
+}
+
+// 2. Fallback: O(1) lookup by resolved URL
+const readyUrlByResolved = preloadOrchestrator.getReadyBlobUrl(resolvedUrl);
+if (readyUrlByResolved) {
+  video.src = readyUrlByResolved;
+}
+```
+
+**Why storage key first:** Presigned URL signatures change on each resolution (X-Amz-Signature differs). Storage keys (e.g., `assets/project/video.mp4`) are canonical and never change.
+
+### Cached Blob URL Fallback
+
+If ready URL not available, create blob URL from cache:
+
+```typescript
+const getCachedBlobUrl = async (url: string): Promise<string | null> => {
+  const cache = await caches.open('tour-builder-assets-v1');
+  const response = await cache.match(url);
+
+  if (response) {
+    const blob = await response.blob();
+    return URL.createObjectURL(blob);
+  }
+
+  return null;
+};
+```
+
+### Usage in Reverse Playback
+
+```typescript
+// useReversePlayback attempts ready/cached URL for better seeking
+// Uses storage key for reliable cache lookup
+const setupReverse = async (storageKey: string) => {
+  // 1. Try instant ready blob URL by storage key (O(1) lookup, most reliable)
+  const readyUrl = preloadOrchestrator.getReadyBlobUrl(storageKey);
+  if (readyUrl) {
+    video.src = readyUrl;
+    isPreloaded = true;
+  } else {
+    // 2. Fallback: create blob URL from cache by storage key
+    const cachedUrl = await getCachedBlobUrl(storageKey);
+    if (cachedUrl) {
+      video.src = cachedUrl;  // Better seeking with local blob
+      isPreloaded = true;
+    }
+  }
+
+  // Proceed with reverse playback
+  startReverse();
+};
+```
+
+---
+
+## Presigned URL Fallback Mechanism
+
+The `useTransitionPlayback` hook includes automatic fallback when presigned S3 URLs fail (typically due to CORS issues):
+
+```typescript
+// Check if URL is a presigned S3 URL
+function isPresignedUrl(url: string): boolean {
+  return url.includes('X-Amz-Signature=') || url.includes('x-amz-signature=');
+}
+
+// Convert presigned URL to proxy URL fallback
+function getProxyUrlFallback(
+  presignedUrl: string,
+  originalStorageKey?: string,
+): string | null {
+  // If we have the original storage key, use it directly
+  if (originalStorageKey && isRelativeStoragePath(originalStorageKey)) {
+    const normalizedPath = originalStorageKey.replace(/^\/+/, '');
+    return `${baseURLApi}/file/download?privateUrl=${encodeURIComponent(normalizedPath)}`;
+  }
+
+  // Try to extract path from presigned URL
+  try {
+    const url = new URL(presignedUrl);
+    const pathParts = url.pathname.split('/').filter(Boolean);
+    if (pathParts.length >= 2) {
+      const storagePath = pathParts.slice(1).join('/');
+      return `${baseURLApi}/file/download?privateUrl=${encodeURIComponent(storagePath)}`;
+    }
+  } catch {
+    // URL parsing failed
+  }
+  return null;
+}
+```
+
+**Fallback Flow:**
+```
+1. Video error event fires on presigned URL
+2. Check if current URL is a presigned S3 URL
+3. If not already tried fallback:
+   a. Mark presigned URL as failed (future resolves use proxy)
+   b. Build proxy fallback URL from storage key
+   c. Retry video load with proxy URL
+4. If fallback also fails → trigger error handler
+```
+
+This mechanism ensures video playback works even when S3 CORS is misconfigured or presigned URLs expire mid-session.
+
+---
+
+## Image Pre-decoding During Transitions
+
+The `useTransitionPlayback` hook supports pre-decoding target page images during the `finishing` phase to ensure instant display after transition:
+
+```typescript
+// In useTransitionPlayback.ts
+async function waitForImages(urls: string[], timeoutMs = 2000): Promise<void> {
+  if (urls.length === 0) return;
+
+  const decodePromises = urls.map(
+    (url) =>
+      new Promise<void>((resolve) => {
+        const img = new Image();
+        img.src = url;
+        if (typeof img.decode === 'function') {
+          img.decode()
+            .then(() => resolve())
+            .catch(() => resolve());
+        } else {
+          img.onload = () => resolve();
+          img.onerror = () => resolve();
+        }
+      }),
+  );
+
+  // Race against timeout to prevent blocking
+  await Promise.race([
+    Promise.all(decodePromises),
+    new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+  ]);
+}
+```
+
+**Usage in Transition Flow:**
+```typescript
+// Enable via features option
+useTransitionPlayback({
+  // ...
+  features: {
+    preDecodeImages: true,
+    getTargetPageImages: () => {
+      // Return URLs of images on the target page
+      return targetPage.elements
+        .filter(el => el.type === 'image')
+        .map(el => resolveAssetUrl(el.imageUrl));
+    },
+  },
+});
+```
+
+This ensures the target page appears instantly without visible image loading after the transition video completes.
+
+---
+
+## Comparison: Constructor vs Runtime
+
+| Aspect | Constructor | Runtime |
+|--------|-------------|---------|
+| **Purpose** | Testing & preview | Presentation playback |
+| **Controls** | Full manual control | Automated flow |
+| **Logging** | Detailed debug logs | Silent operation |
+| **Network Info** | Displayed in UI | Transparent |
+| **Buffering** | Status shown | Hidden from user |
+| **Error Handling** | Detailed messages | Fallback timers |
+| **Duration Source** | Editable input | From transition data |
+
+---
+
+## Error Handling
+
+### Reverse Playback Failures
+
+```typescript
+const handleReverseError = (error: Error) => {
+  console.error('Reverse playback failed:', error);
+
+  // Fallback chain:
+  // 1. Native reverse fails → Try frame-stepping
+  // 2. Frame-stepping fails → Use available buffer
+  // 3. Buffer timeout → Complete with partial playback
+  // 4. All fails → Skip transition, navigate directly
+
+  if (currentStrategy === 'native') {
+    switchToFrameStepping();
+  } else {
+    completeWithAvailableProgress();
+  }
+};
+```
+
+### Forward Playback Failures
+
+```typescript
+const handleVideoError = (event: Event) => {
+  console.error('Video playback error:', event);
+
+  // Ensure navigation continues
+  clearTimeout(fallbackTimer);
+  finishTransition();
+};
+```
+
+### Network Failures
+
+```typescript
+// Video stalls during loading
+video.onstalled = () => {
+  console.warn('Video stalled, waiting for data...');
+  // Don't block - fallback timer will handle
+};
+
+video.onwaiting = () => {
+  setIsBuffering(true);
+};
+
+video.onplaying = () => {
+  setIsBuffering(false);
+};
+```
+
+---
+
+## Performance Optimizations
+
+### 1. Adaptive Frame Rate
+
+```typescript
+// Adjust FPS based on video availability
+const fps = isPreloaded ? 30 : 15;
+```
+
+### 2. Blob URL Caching
+
+```typescript
+// Use cached blob URLs for better seeking
+const cachedUrl = await getCachedBlobUrl(videoUrl);
+if (cachedUrl) {
+  video.src = cachedUrl;
+}
+```
+
+### 3. Preload Priority
+
+Videos receive priority based on context:
+
+```typescript
+const videoPriority = {
+  currentPage: 1000,     // Current page assets
+  neighborBase: 500,     // Neighbor page assets
+  transition: 150,       // Highest type priority - needed immediately on click
+  image: 100,            // Backgrounds load during transition
+  audio: 50,
+  video: 30,             // Background videos can stream progressively
+};
+```
+
+**Note:** `maxNeighborDepth` defaults to 1 (immediate neighbors only). Transition videos have the highest type priority (+150) because they're needed immediately when navigation is triggered.
+
+### 4. Memory Management
+
+```typescript
+// Clean up blob URLs
+useEffect(() => {
+  return () => {
+    if (blobUrl) {
+      URL.revokeObjectURL(blobUrl);
+    }
+  };
+}, [blobUrl]);
+
+// Cancel animation frames
+useEffect(() => {
+  return () => {
+    if (animationFrameId) {
+      cancelAnimationFrame(animationFrameId);
+    }
+  };
+}, []);
+```
+
+### 5. Event Listener Cleanup
+
+```typescript
+useEffect(() => {
+  const video = videoRef.current;
+
+  video.addEventListener('timeupdate', handleTimeUpdate);
+  video.addEventListener('ended', handleEnded);
+
+  return () => {
+    video.removeEventListener('timeupdate', handleTimeUpdate);
+    video.removeEventListener('ended', handleEnded);
+  };
+}, []);
+```
+
+---
+
+## Key Files Reference
+
+| File | Location | LOC | Purpose |
+|------|----------|-----|---------|
+| `useTransitionPlayback.ts` | `frontend/src/hooks/` | 778 | Transition video playback coordination |
+| `useReversePlayback.ts` | `frontend/src/hooks/` | 399 | Reverse playback logic |
+| `useBackgroundVideoPlayback.ts` | `frontend/src/hooks/` | ~210 | Background video time control, session-scoped play-once when loop=false |
+| `usePreloadOrchestrator.ts` | `frontend/src/hooks/` | - | Asset preloading with ready blob URLs |
+| `usePageSwitch.ts` | `frontend/src/hooks/` | - | Page navigation with preloaded assets |
+| `mediaDuration.ts` | `frontend/src/lib/` | 120 | Duration extraction utility |
+| `assetUrl.ts` | `frontend/src/lib/` | - | URL resolution with presigned cache |
+| `extractPageLinks.ts` | `frontend/src/lib/` | - | Extract navigation links with transition videos |
+| `StorageManager.ts` | `frontend/src/lib/offline/` | - | Cache API storage for video blobs |
+| `VideoPlayerElement.tsx` | `frontend/src/components/UiElements/elements/` | 52 | Video player UI element |
+| `RuntimePresentation.tsx` | `frontend/src/components/` | - | Runtime video rendering |
+| `constructor.tsx` | `frontend/src/pages/` | - | Constructor video preview |
+| `[projectSlug]/index.tsx` | `frontend/src/pages/p/` | - | Production runtime page |
+| `[projectSlug]/stage.tsx` | `frontend/src/pages/p/` | - | Stage runtime page |
+| `preload.config.ts` | `frontend/src/config/` | - | Video priority settings (transition: 150) |
+
+---
+
+## Troubleshooting
+
+### Video Won't Play
+1. Check browser autoplay policy (must be muted)
+2. Verify video URL resolves correctly
+3. Check CORS headers on video source
+4. Ensure video format is supported (MP4/WebM)
+
+### Reverse Playback Choppy
+1. Check if video is preloaded (should use 30 FPS)
+2. Verify sufficient buffer is available
+3. Try using cached blob URL for better seeking
+4. Consider reducing video resolution
+
+### Transition Doesn't Complete
+1. Check `onEnded` event fires correctly
+2. Verify fallback timer is set
+3. Look for JavaScript errors in console
+4. Ensure `finishTransition` is called
+
+### Memory Leaks
+1. Verify blob URLs are revoked on cleanup
+2. Check animation frames are cancelled
+3. Ensure event listeners are removed
+4. Look for orphaned video elements
diff --git a/frontend/README.md b/frontend/README.md
index cd05092..efc017b 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -46,6 +46,16 @@ npm run lint      # ESLint check (.ts, .tsx files)
 npm run format    # Format code with Prettier
 ```
 
+## Documentation
+
+- [Frontend architecture](docs/frontend-architecture.md) - app structure, runtime flow, and frontend module map
+- [Pages module](docs/pages-module.md) - page routing and major page responsibilities
+- [Components module](docs/components-module.md) - shared and feature component documentation
+- [Hooks module](docs/hooks-module.md) - custom hook inventory and patterns
+- [Runtime presentation](docs/runtime-presentation.md) - public/stage playback flow and access behavior
+- [Assets preloading](../documentation/assets-preloading.md) - cross-platform preloading strategy and S3 direct downloads
+- [UI elements](../documentation/ui-elements.md) - element model stored in `ui_schema_json`
+
 ## Project Structure
 
 ```
diff --git a/frontend/docs/asset-upload-preloading-pwa-analysis.md b/frontend/docs/asset-upload-preloading-pwa-analysis.md
new file mode 100644
index 0000000..20d26b3
--- /dev/null
+++ b/frontend/docs/asset-upload-preloading-pwa-analysis.md
@@ -0,0 +1,835 @@
+# Asset Upload, Preloading, PWA & Offline Mode Analysis
+
+## Executive Summary
+
+Deep analysis of how pages and assets are uploaded, preloaded, and cached in the Tour Builder Platform - covering Constructor editing, Runtime Presentations, and Online/Offline modes. This document traces each thread step-by-step to verify robustness.
+
+---
+
+## 1. SYSTEM ARCHITECTURE OVERVIEW
+
+### 1.1 Core Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| `UploadService` | `components/Uploaders/UploadService.js` | File upload to backend (simple + chunked) |
+| `usePreloadOrchestrator` | `hooks/usePreloadOrchestrator.ts` | Priority queue preloading with blob URL cache |
+| `useNetworkAware` | `hooks/useNetworkAware.ts` | Network condition monitoring |
+| `useOfflineMode` | `hooks/useOfflineMode.ts` | Project download for offline use |
+| `StorageManager` | `lib/offline/StorageManager.ts` | Cache API / IndexedDB abstraction |
+| `OfflineDbManager` | `lib/offlineDb/OfflineDbManager.ts` | IndexedDB CRUD operations |
+| `DownloadManager` | `lib/offline/DownloadManager.ts` | Download queue with pause/resume |
+| `DownloadEventBus` | `lib/offline/DownloadEventBus.ts` | Progress event emitter |
+| `sw.ts` | `src/sw.ts` | Service Worker (Serwist) |
+
+### 1.2 Storage Hierarchy
+
+```
+Storage Layer Decision (based on file size)
+    |
++-- Cache API (< 5MB)
+|   +-- Fast browser cache
+|   +-- Used for images, audio, small videos
+|   +-- Service Worker intercepts requests
+|
++-- IndexedDB (>= 5MB) via Dexie.js
+|   +-- assets table: large files (videos)
+|   +-- projects table: offline project metadata
+|   +-- downloadQueue table: resumable download state
+|
++-- In-Memory (readyBlobUrlsRef)
+    +-- Map<originalUrl, blobUrl>
+    +-- Pre-decoded images for instant display
+    +-- O(1) lookup during navigation
+```
+
+---
+
+## 2. ASSET UPLOAD PIPELINE
+
+### 2.1 Simple Upload Flow (Constructor)
+
+```
+FormFilePicker / FormImagePicker
+    |
+handleFileChange(event)
+    |
+FileUploader.validate(file, schema)
+    +-- Check assetType (image/video/audio)
+    +-- Check file size
+    +-- Check extensions
+    |
+FileUploader.upload(path, file, schema)
+    |
+uploadToServer(file, path, filename)
+    |
+POST /api/file/upload/{table}/{field}
+    +-- multipart/form-data
+    +-- JWT authentication required
+    |
+Backend services.uploadFile()
+    +-- S3: PutObjectCommand
+    +-- GCloud: storage.bucket().upload()
+    +-- Local: fs.writeFile()
+    |
+Return { id, name, sizeInBytes, privateUrl, publicUrl }
+```
+
+**File Paths:**
+- `FormFilePicker.tsx:53-63` - handleFileChange
+- `UploadService.js:130-152` - upload()
+- `backend/src/routes/file.js:63-71` - POST /upload
+- `backend/src/services/file/index.ts` - uploadFile()
+
+### 2.2 Chunked Upload Flow (Large Files)
+
+```
+FileUploader.uploadChunked(path, file, schema, options)
+    |
+POST /api/file/upload-sessions/init
+    +-- { folder, filename, size, contentType, totalChunks }
+    +-- Returns: { sessionId }
+    |
+For each chunk (5MB default):
+    PUT /api/file/upload-sessions/{sessionId}/chunks/{chunkIndex}
+        +-- Raw binary data (application/octet-stream)
+        +-- Retry up to 3 times with exponential backoff
+        +-- onProgress callback for UI updates
+    |
+POST /api/file/upload-sessions/{sessionId}/finalize
+    +-- Combines all chunks
+    +-- Returns: { url }
+    |
+Return { id, name, sizeInBytes, privateUrl, publicUrl }
+```
+
+**File Paths:**
+- `UploadService.js:154-280` - uploadChunked()
+- `backend/src/routes/file.js:73-106` - Session endpoints
+
+### 2.3 Upload Validation
+
+```javascript
+// UploadService.js:77-128
+validate(file, schema) {
+    // Asset type validation (MIME + extension)
+    if (schema.assetType) validateAssetType(file, expectedType)
+
+    // Legacy validators
+    if (schema.image) validateAssetType(file, 'image')
+    if (schema.video) validateAssetType(file, 'video')
+    if (schema.audio) validateAssetType(file, 'audio')
+
+    // Size limit
+    if (schema.size && file.size > schema.size) throw Error
+
+    // Extension whitelist
+    if (schema.formats && !formats.includes(ext)) throw Error
+}
+```
+
+---
+
+## 3. PRELOAD ORCHESTRATOR
+
+### 3.1 Initialization Flow
+
+```
+usePreloadOrchestrator(options)
+    |
+options = {
+    pages,           // All tour pages
+    pageLinks,       // Navigation links between pages
+    elements,        // UI elements with asset URLs
+    currentPageId,   // Currently viewed page
+    enabled,         // Enable/disable preloading
+    maxNeighborDepth // How deep to preload (default: 1)
+}
+    |
+Initialize hooks:
+    +-- useNeighborGraph() - Build navigation graph
+    +-- useNetworkAware() - Monitor network status
+    |
+Initialize refs:
+    +-- queueRef: PreloadQueueItem[]
+    +-- readyBlobUrlsRef: Map<url, blobUrl>
+    +-- failedCacheLookupRef: Set<url>
+```
+
+### 3.2 Page Change -> Preload Trigger
+
+```
+useEffect triggers when currentPageId changes
+    |
+Guard: if (!enabled || !currentPageId || !networkInfo.isOnline) return
+    |
+Skip if already preloaded for this page (same pageId + linksCount)
+    |
+neighborGraph.getPrioritizedAssets(currentPageId, maxNeighborDepth)
+    +-- Returns assets sorted by priority
+    |
+Collect storage paths for presigning:
+    +-- Current page: background_image_url, background_video_url, background_audio_url
+    +-- Neighbor pages: same background URLs
+    +-- Element assets: iconUrl, imageUrl, mediaUrl, transitionVideoUrl, etc.
+    |
+queuePresignedUrls(storagePaths)
+    +-- POST /api/file/presign { urls: [...] }
+    +-- Returns: { presignedUrls: { path: signedUrl } }
+    +-- Cache results for 1 hour (PRESIGN_TTL_MS)
+    |
+addAssetsToQueue()
+    +-- Current page backgrounds: priority = 1000 + 200/150/100
+    +-- Element assets: priority from neighbor graph
+    +-- Neighbor backgrounds: priority = 500 + 100/50/30
+```
+
+**File Paths:**
+- `usePreloadOrchestrator.ts:669-924` - Page change effect
+- `assetUrl.ts:164-223` - queuePresignedUrls()
+
+### 3.3 Queue Processing (CRITICAL FOR ONLINE MODE)
+
+```
+processQueue()                               [lines 354-491]
+    |
+Guard: if (isProcessingRef.current) return
+Guard: if (!networkInfo.isOnline) return     [*** OFFLINE GUARD ***]
+Guard: if (queueRef.current.length === 0) return
+    |
+isProcessingRef.current = true
+setIsPreloading(true)
+    |
+While queue not empty && activeDownloads < recommendedConcurrency:
+    |
+    item = queueRef.current.shift()
+    |
+    if (preloadedUrls.has(item.url)) continue    [Skip if done]
+    |
+    cached = await isUrlCached(item.url)         [Check cache]
+        +-- StorageManager.hasAsset(url)
+        +-- Checks IndexedDB first, then Cache API
+    |
+    if (cached) {
+        await createReadyBlobUrl(item.url, item.storageKey)
+        continue
+    }
+    |
+    activeDownloadsRef.current++
+    |
+    preloadWithProgress(item.url, jobId, assetId)
+        +-- fetch(url) with streaming progress
+        +-- Store in Cache API
+        +-- downloadEventBus.emitPreloadProgress()
+        |
+    .then(() => {
+        createReadyBlobUrl(item.url, item.storageKey)
+        markPresignedUrlsVerified()
+        |
+        // Store under storage key for post-refresh lookups
+        cache.put(item.storageKey, existingResponse.clone())
+    })
+    .catch(() => {
+        // If presigned URL failed (CORS), retry with proxy
+        if (isPresignedUrl(item.url)) {
+            markPresignedUrlFailed(item.storageKey)
+            proxyUrl = buildProxyUrl(item.storageKey)
+            await preloadWithProgress(proxyUrl, ...)
+            await createReadyBlobUrl(proxyUrl, item.storageKey)
+        }
+    })
+    .finally(() => {
+        activeDownloadsRef.current--
+        processQueue()  // Continue processing
+    })
+```
+
+### 3.4 Blob URL Creation (Instant Display Ready)
+
+```
+createReadyBlobUrl(url, storageKey?)         [lines 280-352]
+    |
+Guard: if (failedCacheLookupRef.has(url)) return
+    |
+blob = await StorageManager.getAsset(url)
+    |
+if (!blob && storageKey) {
+    blob = await StorageManager.getAsset(storageKey)
+}
+    |
+if (!blob && storageKey) {
+    // Try proxy URL format as fallback
+    proxyUrl = `${baseURLApi}/file/download?privateUrl=...`
+    blob = await StorageManager.getAsset(proxyUrl)
+}
+    |
+if (!blob) {
+    failedCacheLookupRef.add(url)        [Prevent retry loops]
+    return
+}
+    |
+blobUrl = URL.createObjectURL(blob)
+    |
+if (isImageUrl(url)) {
+    await decodeImage(blobUrl)           [Pre-decode for instant paint]
+}
+    |
+readyBlobUrlsRef.current.set(url, blobUrl)
+readyBlobUrlsRef.current.set(storageKey, blobUrl)  [Dual mapping]
+preloadedUrls.add(url)
+```
+
+### 3.5 Instant Lookup API
+
+```
+getReadyBlobUrl(url): string | null          [line 582-584]
+    |
+return readyBlobUrlsRef.current.get(url) || null
+    |
+O(1) Map lookup - used during page navigation for instant display
+```
+
+---
+
+## 4. NETWORK AWARENESS
+
+### 4.1 Network Information API
+
+```
+useNetworkAware()                            [hooks/useNetworkAware.ts]
+    |
+getConnection()
+    +-- navigator.connection
+    +-- navigator.mozConnection
+    +-- navigator.webkitConnection
+    |
+getNetworkInfo() returns:
+    +-- isOnline: navigator.onLine
+    +-- effectiveType: 'slow-2g' | '2g' | '3g' | '4g'
+    +-- downlink: Mbps
+    +-- rtt: milliseconds
+    +-- saveData: boolean
+```
+
+### 4.2 Event Listeners
+
+```
+useEffect()                                  [lines 72-96]
+    |
+window.addEventListener('online', updateNetworkInfo)
+window.addEventListener('offline', updateNetworkInfo)
+    |
+if (connection) {
+    connection.addEventListener('change', updateNetworkInfo)
+}
+```
+
+### 4.3 Adaptive Behavior
+
+```
+shouldPreloadAggressively():                 [lines 99-108]
+    if (!networkInfo.isOnline) return false
+    if (networkInfo.saveData) return false
+    if (effectiveType === '4g') return true
+    if (downlink >= 5) return true
+    return false
+
+recommendedConcurrency():                    [lines 121-143]
+    if (!isOnline) return 0
+    if (saveData) return 1
+    switch (effectiveType):
+        'slow-2g': 1
+        '2g': 1
+        '3g': 2
+        '4g': 3
+        default: 2
+
+suggestOfflineMode():                        [lines 146-154]
+    if (effectiveType === 'slow-2g') return true
+    if (effectiveType === '2g') return true
+    if (rtt > 500) return true
+    if (downlink < 0.5) return true
+    return false
+```
+
+---
+
+## 5. OFFLINE MODE FUNCTIONALITY
+
+### 5.1 Project Download Flow
+
+```
+useOfflineMode({ projectId, projectSlug, projectName, pages })
+    |
+On mount: loadProjectInfo()
+    +-- OfflineDbManager.getProject(projectId)
+    +-- Restore status, progress from IndexedDB
+    |
+startDownload()                              [lines 258-420]
+    |
+setStatus('downloading')
+    |
+assets = discoverAssets()  // Frontend-only asset discovery
+    +-- extractPageLinksAndElements(pages)
+    +-- discoverProjectAssets(pages, pageLinks, preloadElements)
+    +-- Returns: AssetToCache[] (same as online preload)
+    |
+estimatedTotalSize = assets.reduce((sum, a) => sum + (a.sizeBytes || 0), 0)
+    |
+quota = await StorageManager.getStorageQuota()
+if (!quota.canStore(estimatedTotalSize)) throw 'Insufficient storage'
+    |
+await OfflineDbManager.upsertProject({
+    id: projectId,
+    slug, name, status: 'downloading',
+    totalAssets: assets.length, downloadedAssets: 0,
+    totalSizeBytes: estimatedTotalSize, downloadedSizeBytes: 0,
+    version: `v${Date.now()}`
+})
+    |
+For each asset:
+    assetInfo = await StorageManager.getAssetInfo(asset.storageKey)
+    if (assetInfo?.exists && !assetInfo.isPartial) {
+        downloadedCount++  // Fully cached, skip
+        continue
+    }
+    // Partial cached needs full download for offline
+    |
+presignedUrls = await queuePresignedUrls(storagePaths)
+    |
+    await downloadManager.addJob({
+        assetId: `offline-${storageKey}`,
+        projectId, url: downloadUrl,  // presigned or proxy
+        storageKey, createBlobUrl: true, persist: true
+    })
+    |
+Progress tracked via DownloadEventBus events:
+    downloadEventBus.on('asset-preload-complete', (data) => {
+        // data includes { storageKey }
+        downloadedCount++
+        if (downloadedCount >= totalAssets) {
+            setStatus('downloaded')
+            OfflineDbManager.updateProjectStatus(projectId, 'downloaded')
+            downloadEventBus.emitProjectComplete(...)
+        }
+    })
+```
+
+### 5.2 Download Manager Queue
+
+```
+DownloadManager.addJob(params)               [lines 57-118]
+    |
+Guard: if (await StorageManager.hasAsset(url)) return
+Guard: if (already in queue or active) return
+    |
+job = {
+    id, assetId, projectId, url, filename,
+    variantType, assetType, priority,
+    status: 'queued', progress: 0,
+    retryCount: 0, addedAt: Date.now()
+}
+    |
+await persistQueueItem(job)                  [IndexedDB persistence]
+    |
+Insert in priority order (higher first)
+downloadEventBus.emitQueueUpdate()
+processQueue()
+```
+
+### 5.3 Download with Progress
+
+```
+downloadAsset(job)                           [lines 179-304]
+    |
+job.status = 'downloading'
+job.abortController = new AbortController()
+await OfflineDbManager.updateQueueStatus(job.id, 'downloading')
+downloadEventBus.emitPreloadStart(...)
+    |
+response = await fetch(job.url, { signal: job.abortController.signal })
+    |
+if (response.body) {
+    // Stream with progress
+    reader = response.body.getReader()
+    while (!done) {
+        { done, value } = await reader.read()
+        chunks.push(value)
+        bytesLoaded += value.length
+        progress = (bytesLoaded / totalBytes) * 100
+        downloadEventBus.emitPreloadProgress(...)
+        await OfflineDbManager.updateQueueProgress(...)
+    }
+    blob = new Blob(chunks, { type })
+} else {
+    blob = await response.blob()
+}
+    |
+await StorageManager.storeAsset(url, blob, metadata)
+    |
+job.status = 'completed'
+await OfflineDbManager.removeFromQueue(job.id)
+downloadEventBus.emitPreloadComplete(...)
+```
+
+### 5.4 Pause/Resume/Cancel
+
+```
+pauseAll()                                   [lines 309-316]
+    isPaused = true
+    activeDownloads.forEach(job => {
+        job.abortController?.abort()
+        job.status = 'paused'
+    })
+
+resumeAll()                                  [lines 321-335]
+    isPaused = false
+    activeDownloads.forEach(job => {
+        if (job.status === 'paused') {
+            job.status = 'queued'
+            queue.unshift(job)
+        }
+    })
+    activeDownloads.clear()
+    processQueue()
+
+cancelProjectDownloads(projectId)            [lines 365-381]
+    // Abort active, remove from queue, clear IndexedDB
+```
+
+### 5.5 Queue Restoration (Resume After Page Reload)
+
+```
+restoreQueue()                               [lines 418-458]
+    |
+pendingItems = await OfflineDbManager.getPendingQueue()
+    |
+for (item of pendingItems) {
+    if (await StorageManager.hasAsset(item.url)) {
+        await OfflineDbManager.removeFromQueue(item.id)
+        continue
+    }
+    |
+    // Re-add to in-memory queue
+    queue.push({ ...item, status: 'queued' })
+}
+    |
+queue.sort((a, b) => b.priority - a.priority)
+downloadEventBus.emitQueueUpdate()
+processQueue()
+```
+
+---
+
+## 6. STORAGE MANAGER
+
+### 6.1 Storage Decision Logic
+
+```
+storeAsset(url, blob, metadata)              [lines 89-130]
+    |
+sizeBytes = blob.size
+    |
+if (sizeBytes >= OFFLINE_CONFIG.storage.indexedDbMinSize) {  // 5MB
+    // Large file -> IndexedDB
+    asset = { id, projectId, url, filename, variantType, assetType, mimeType, sizeBytes, blob, downloadedAt }
+    await OfflineDbManager.storeAsset(asset)
+} else {
+    // Small file -> Cache API
+    cache = await caches.open(OFFLINE_CONFIG.cacheNames.assets)
+    response = new Response(blob, { headers: { 'Content-Type': blob.type, ... } })
+    await cache.put(url, response)
+}
+```
+
+### 6.2 Asset Retrieval (Both Layers)
+
+```
+getAsset(url): Promise<Blob | null>          [lines 135-152]
+    |
+// Check IndexedDB first (large files)
+indexedAsset = await OfflineDbManager.getAssetByUrl(url)
+if (indexedAsset) return indexedAsset.blob
+    |
+// Check Cache API
+cache = await caches.open(OFFLINE_CONFIG.cacheNames.assets)
+response = await cache.match(url)
+if (response) return response.blob()
+    |
+return null
+
+hasAsset(url): Promise<boolean>              [lines 157-170]
+    |
+if (await OfflineDbManager.hasAssetByUrl(url)) return true
+    |
+cache = await caches.open(OFFLINE_CONFIG.cacheNames.assets)
+response = await cache.match(url)
+if (response) return true
+    |
+return false
+```
+
+### 6.3 Storage Quota
+
+```
+getStorageQuota(): Promise<StorageQuotaInfo> [lines 22-56]
+    |
+{ usage, quota } = await navigator.storage.estimate()
+percentUsed = (usage / quota) * 100
+available = quota - usage
+    |
+return {
+    usage, quota, percentUsed, available,
+    canStore: (bytes) => available - bytes > PRELOAD_CONFIG.storage.minFreeBuffer
+}
+
+requestPersistentStorage(): Promise<boolean> [lines 61-76]
+    |
+isPersisted = await navigator.storage.persisted()
+if (isPersisted) return true
+return await navigator.storage.persist()
+```
+
+---
+
+## 7. SERVICE WORKER (PWA)
+
+### 7.1 Serwist Configuration
+
+```
+sw.ts                                        [lines 97-211]
+    |
+new Serwist({
+    precacheEntries: self.__SW_MANIFEST,
+    skipWaiting: true,
+    clientsClaim: true,
+    navigationPreload: true,
+    runtimeCaching: [
+        // Static assets: CacheFirst
+        { matcher: image/font/css/js, handler: CacheFirst, cacheName: 'tour-builder-assets-v1' },
+
+        // Videos: CacheFirst with Range support
+        { matcher: .mp4/.webm/.mov, handler: CacheFirst + range plugin },
+
+        // API: NetworkFirst
+        { matcher: /api/*, handler: NetworkFirst, cacheName: 'api-cache' },
+
+        // Dynamic assets: CacheFirst
+        { matcher: cacheable && !video, handler: CacheFirst, cacheName: 'tour-builder-assets-v1' }
+    ]
+})
+```
+
+### 7.2 Video Range Request Support (CRITICAL)
+
+```
+cachedResponseWillBeUsed plugin              [lines 138-169]
+    |
+rangeHeader = request.headers.get('range')
+if (!rangeHeader) return cachedResponse
+    |
+match = rangeHeader.match(/bytes=(\d+)-(\d*)/)
+start = parseInt(match[1])
+end = match[2] ? parseInt(match[2]) : undefined
+    |
+blob = await cachedResponse.blob()
+slicedBlob = end ? blob.slice(start, end + 1) : blob.slice(start)
+    |
+return new Response(slicedBlob, {
+    status: 206,
+    statusText: 'Partial Content',
+    headers: {
+        'Content-Type': 'video/mp4',
+        'Content-Range': `bytes ${start}-${end}/${blob.size}`,
+        'Accept-Ranges': 'bytes'
+    }
+})
+```
+
+### 7.3 Message Handlers
+
+```
+self.addEventListener('message', handler)    [lines 214-295]
+    |
+CACHE_ASSETS: { urls: string[] }
+    +-- Fetch each URL and put in 'tour-builder-assets-v1' cache
+
+CACHE_VIDEO_CHUNK: { url, chunk, contentType }
+    +-- Store video chunk for progressive playback
+
+CLEAR_CACHE:
+    +-- Delete 'tour-builder-dynamic-v1' and 'tour-builder-assets-v1'
+
+GET_CACHE_STATUS:
+    +-- Return { cachedCount, urls } to main thread
+
+SKIP_WAITING:
+    +-- self.skipWaiting() for immediate activation
+```
+
+---
+
+## 8. ONLINE/OFFLINE MODE SWITCHING
+
+### 8.1 Going Offline
+
+```
+Network disconnects
+    |
+window 'offline' event fires
+    |
+useNetworkAware updates: networkInfo.isOnline = false
+    |
+usePreloadOrchestrator.processQueue():
+    Guard: if (!networkInfo.isOnline) return    [QUEUE PAUSED]
+    |
+Assets already cached remain accessible:
+    +-- StorageManager.getAsset(url) works offline
+    +-- getCachedBlobUrl(url) works offline
+    +-- getReadyBlobUrl(url) works offline (in-memory)
+    |
+Navigation still works if assets are cached:
+    +-- usePageSwitch.resolveToDisplayUrl() checks cache first
+    +-- useTransitionPlayback checks getReadyBlobUrl/getCachedBlobUrl
+```
+
+### 8.2 Coming Back Online
+
+```
+Network reconnects
+    |
+window 'online' event fires
+    |
+useNetworkAware updates: networkInfo.isOnline = true
+    |
+usePreloadOrchestrator.processQueue():
+    Resumes queue processing automatically
+    |
+useOfflineMode.resumeDownload():
+    downloadManager.resumeAll()
+```
+
+### 8.3 Robustness Verification
+
+| Scenario | Behavior | Status |
+|----------|----------|--------|
+| Offline during preload | Queue pauses, cached assets work | ROBUST |
+| Offline during navigation | Uses cached assets if available | ROBUST |
+| Offline during transition video | Uses cached video if available | ROBUST |
+| Online -> Offline mid-download | Download fails, retries when online | ROBUST |
+| Page refresh while offline | Queue restored from IndexedDB | ROBUST |
+| Offline project download | Works if manifest was fetched | ROBUST |
+
+---
+
+## 9. ASSET URL RESOLUTION
+
+### 9.1 resolveAssetPlaybackUrl Flow
+
+```
+resolveAssetPlaybackUrl(value)               [assetUrl.ts:329-357]
+    |
+normalized = String(value).trim()
+if (!normalized) return ''
+    |
+// Passthrough URLs
+if (data: or blob:) return normalized
+if (/api/file/download) return normalized
+if (/file/download) return baseURLApi + normalized
+if (http:// or https://) return normalized
+    |
+// Relative storage path
+presigned = getPresignedUrl(normalized)      [Check cache]
+if (presigned) return presigned
+    |
+// Fallback to backend proxy
+return `${baseURLApi}/file/download?privateUrl=${encodeURIComponent(normalized)}`
+```
+
+### 9.2 Presigned URL Management
+
+```
+queuePresignedUrls(storageKeys)              [assetUrl.ts:164-223]
+    |
+if (presignedUrlsDisabled) return {}
+    |
+uncachedKeys = keys.filter(not in cache or expired)
+    |
+Add to pendingBatch[]
+    |
+Schedule batch processing (10ms debounce)
+    |
+processBatch()
+    POST /api/file/presign { urls: [...] }
+    |
+    Cache results: presignedUrlCache.set(key, { url, expiresAt })
+```
+
+### 9.3 CORS Failure Handling
+
+```
+axios interceptor detects presigned URL failure
+    |
+disablePresignedUrls()
+    presignedUrlsDisabled = true
+    presignedUrlCache.clear()
+    |
+All future requests use proxy URL:
+    /api/file/download?privateUrl={path}
+```
+
+---
+
+## 10. CRITICAL CODE LOCATIONS
+
+| Feature | File | Lines |
+|---------|------|-------|
+| Upload validation | `UploadService.js` | 77-128 |
+| Upload to server | `UploadService.js` | 282-296 |
+| Chunked upload | `UploadService.js` | 154-280 |
+| Preload queue guard | `usePreloadOrchestrator.ts` | 357 |
+| Queue processing | `usePreloadOrchestrator.ts` | 354-491 |
+| Blob URL creation | `usePreloadOrchestrator.ts` | 280-352 |
+| Instant lookup | `usePreloadOrchestrator.ts` | 582-584 |
+| Network monitoring | `useNetworkAware.ts` | 72-96 |
+| Concurrency calc | `useNetworkAware.ts` | 121-143 |
+| Project download | `useOfflineMode.ts` | 158-295 |
+| Download with progress | `DownloadManager.ts` | 179-304 |
+| Queue restoration | `DownloadManager.ts` | 418-458 |
+| Storage decision | `StorageManager.ts` | 82-84 |
+| Asset retrieval | `StorageManager.ts` | 135-152 |
+| Video range support | `sw.ts` | 138-169 |
+| SW message handlers | `sw.ts` | 214-295 |
+| URL resolution | `assetUrl.ts` | 329-357 |
+| Presigned batch | `assetUrl.ts` | 164-223 |
+
+---
+
+## 11. ROBUSTNESS CONCLUSION
+
+### 11.1 Key Strengths
+
+1. **Dual Storage Strategy** - Cache API for small files, IndexedDB for large files
+2. **Queue Persistence** - IndexedDB stores download queue for resume after refresh
+3. **Network Awareness** - Adaptive concurrency based on connection quality
+4. **Offline Guard** - Preload queue pauses when offline, cached assets work
+5. **Presigned URL Fallback** - Automatically falls back to proxy on CORS failure
+6. **Video Range Requests** - Service Worker handles seeking in cached videos
+7. **Progress Tracking** - EventBus pattern for real-time download progress
+8. **Blob URL Cache** - Pre-decoded images for instant display (O(1) lookup)
+
+### 11.2 Verified Scenarios
+
+- Asset upload (simple + chunked): WORKING
+- Preload queue online: WORKING
+- Preload queue offline: PAUSES (correct behavior)
+- Navigation with cached assets offline: WORKING
+- Project download for offline: WORKING
+- Pause/Resume downloads: WORKING
+- Queue restoration after refresh: WORKING
+- Video seeking offline: WORKING (range requests)
+- Mode switching (online/offline): WORKING
+
+### 11.3 No Critical Gaps Identified
+
+The offline mode functionality is robust and handles all edge cases properly.
diff --git a/frontend/docs/components-module.md b/frontend/docs/components-module.md
new file mode 100644
index 0000000..3f516e8
--- /dev/null
+++ b/frontend/docs/components-module.md
@@ -0,0 +1,1079 @@
+# Frontend Components Module
+
+## Overview
+
+The Components module contains **194 TypeScript files** that provide the React component library for the Tour Builder Platform. Components are organized by domain, function, and factory patterns to maximize reuse.
+
+**Location:** `frontend/src/components/`
+
+---
+
+## Architecture Diagram
+
+```
+frontend/src/components/
+│
+├── Entity Components (13 directories, 52+ files)
+│   ├── Users/          # TableUsers, configureUsersCols, CardUsers, ListUsers
+│   ├── Projects/       # TableProjects, configureProjectsCols, ...
+│   ├── Assets/         # TableAssets, configureAssetsCols, useAssetUploader
+│   ├── Roles/          # TableRoles, configureRolesCols, ...
+│   └── ... (9 more entity directories)
+│
+├── Uploaders/
+│   └── UploadService.js             # Chunked upload with MIME validation
+│
+├── Factory Components
+│   ├── Factory/createTableComponent.tsx      # Table component generator
+│   └── DataGrid/configBuilderFactory.tsx     # Column config generator
+│
+├── Generic Components
+│   ├── Generic/GenericTable.tsx              # Base table with DataGrid
+│   └── Generic/GenericFormField.tsx          # Form field wrapper
+│
+├── Constructor Components (15 files)
+│   ├── CanvasElement.tsx                     # Canvas element rendering
+│   ├── ElementEditorPanel.tsx                # Element settings sidebar
+│   ├── ConstructorControlsPanel.tsx          # Editor controls
+│   └── ...
+│
+├── ElementSettings (23 files)
+│   ├── CommonSettingsSection.tsx             # Position, timing
+│   ├── NavigationSettingsSection.tsx         # Navigation links
+│   ├── StyleSettingsSection.tsx              # CSS properties
+│   └── ... (Full + Compact variants, types, hooks)
+│
+├── UiElements (16 files)
+│   ├── UiElementRenderer.tsx                 # Unified element renderer
+│   ├── shared/useElementWrapperStyle.ts      # Shared styling hook
+│   ├── GalleryCarouselOverlay.tsx            # Gallery/Carousel overlay component
+│   └── elements/ (10 per-type components)    # NavigationElement, GalleryElement, etc.
+│
+├── Offline/PWA (5 files)
+│   ├── OfflineStatusIndicator.tsx
+│   ├── DownloadProgressPanel.tsx
+│   └── ...
+│
+├── Runtime/ (1 file)
+│   └── RuntimeControls.tsx             # Configurable offline/fullscreen/sound controls
+│
+├── Layout Components
+│   ├── NavBar.tsx                            # Top navigation
+│   ├── AsideMenu.tsx                         # Sidebar navigation
+│   ├── FooterBar.tsx                         # Footer
+│   └── SectionMain.tsx                       # Main content wrapper
+│
+└── Standalone Components (~50 files)
+    ├── BaseButton.tsx                        # Button component
+    ├── CardBox.tsx                           # Card container
+    ├── FormField.tsx                         # Form field wrapper
+    ├── RuntimePresentation.tsx               # Tour playback
+    ├── RuntimeElement.tsx                    # Runtime element wrapper
+    ├── TourFlowManager.tsx                   # Page management
+    └── ...
+```
+
+---
+
+## Component Categories
+
+### 1. Entity Components (13 Directories)
+
+Each entity has a dedicated directory with consistent structure.
+
+**Entities:**
+- `Users/`, `Roles/`, `Permissions/`
+- `Projects/`, `Project_memberships/`
+- `Assets/`, `Asset_variants/`
+- `Tour_pages/`, `Project_audio_tracks/`
+- `Publish_events/`, `Pwa_caches/`
+- `Access_logs/`, `Presigned_url_requests/`
+
+**Standard Files per Entity:**
+
+| File | Purpose | Generator |
+|------|---------|-----------|
+| `Table[Entity].tsx` | Data grid table | `createTableComponent` |
+| `configure[Entity]Cols.tsx` | Column definitions | `createColumnLoader` |
+| `Card[Entity].tsx` | Card display | Manual |
+| `List[Entity].tsx` | List display | Manual |
+
+**Example: TableUsers.tsx (23 LOC)**
+```typescript
+import { createTableComponent } from '../Factory/createTableComponent';
+import {
+  fetch, update, deleteItem, setRefetch, deleteItemsByIds,
+} from '../../stores/users/usersSlice';
+import { loadColumns } from './configureUsersCols';
+import type { User } from '../../types/entities';
+
+const TableUsers = createTableComponent<User>({
+  entityName: 'users',
+  sliceSelector: (state) => state.users,
+  fetchAction: fetch,
+  updateAction: update,
+  deleteAction: deleteItem,
+  deleteByIdsAction: deleteItemsByIds,
+  setRefetchAction: setRefetch,
+  loadColumnsFunction: loadColumns,
+});
+
+export default TableUsers;
+```
+
+**Example: configureUsersCols.tsx**
+```typescript
+import { createColumnLoader, ColumnMetadata } from '../DataGrid/configBuilderFactory';
+
+const USERS_COLUMNS: ColumnMetadata[] = [
+  { field: 'firstName', headerName: 'First Name', type: 'text', editable: true },
+  { field: 'lastName', headerName: 'Last Name', type: 'text', editable: true },
+  { field: 'email', headerName: 'E-Mail', type: 'text', editable: true },
+  { field: 'disabled', headerName: 'Disabled', type: 'boolean', editable: true },
+  {
+    field: 'avatar',
+    headerName: 'Avatar',
+    type: 'image',
+    renderCell: (params) => <ImageField image={params?.row?.avatar} />,
+  },
+  {
+    field: 'app_role',
+    headerName: 'App Role',
+    type: 'singleSelectRelation',
+    entityRef: 'roles',
+    editable: true,
+  },
+  { field: 'actions', headerName: '', type: 'actions' },
+];
+
+export const loadColumns = createColumnLoader({
+  entityName: 'users',
+  columns: USERS_COLUMNS,
+});
+```
+
+---
+
+### 2. Factory Components
+
+#### createTableComponent (Factory/createTableComponent.tsx)
+
+**Purpose:** Generates entity table components from configuration.
+
+**Input Configuration:**
+```typescript
+interface TableComponentConfig<T extends BaseEntity> {
+  entityName: string;
+  sliceSelector: (state: RootState) => EntitySliceState<T>;
+  fetchAction: AsyncThunk<...>;
+  updateAction: AsyncThunk<...>;
+  deleteAction: AsyncThunk<...>;
+  deleteByIdsAction: AsyncThunk<...>;
+  setRefetchAction: (refetch: boolean) => Action;
+  loadColumnsFunction: (onDelete, entityName, user) => Promise<GridColDef[]>;
+}
+```
+
+**Output:** React component wrapping `GenericTable`.
+
+**Usage Pattern:**
+```typescript
+const TableAssets = createTableComponent<Asset>({
+  entityName: 'assets',
+  sliceSelector: (state) => state.assets,
+  fetchAction: fetch,
+  updateAction: update,
+  deleteAction: deleteItem,
+  deleteByIdsAction: deleteItemsByIds,
+  setRefetchAction: setRefetch,
+  loadColumnsFunction: loadColumns,
+});
+```
+
+#### configBuilderFactory (DataGrid/configBuilderFactory.tsx)
+
+**Purpose:** Generates MUI X DataGrid column configurations from metadata.
+
+**Column Types Supported:**
+
+| Type | Description | MUI Type |
+|------|-------------|----------|
+| `text` | Plain text | string |
+| `boolean` | Checkbox | boolean |
+| `date` | Date only | dateTime |
+| `datetime` | Date and time | dateTime |
+| `number` | Numeric | number |
+| `relation` | Single relation | singleSelect |
+| `relationMany` | Multiple relations | singleSelect + DataGridMultiSelect |
+| `singleSelectRelation` | Dropdown relation | singleSelect |
+| `image` | Image thumbnail | custom renderCell |
+| `actions` | Row actions | actions |
+
+**Features:**
+- Auto-fetches relation options via `/[entity]/autocomplete?limit=50` to match the backend autocomplete limit
+- Formats `singleSelectRelation` values from either loaded `{ id, label }` options or nested relation objects, so list tables display names instead of UUIDs
+- AsyncPaginate relation fields (`SelectField`, `SelectFieldMany`, `RoleSelect`) use page size `50` for the same backend limit
+- Permission-aware editable fields
+- Custom formatters via `dataFormatter`
+- Action column with view/edit/delete popover
+
+---
+
+### 3. Generic Components
+
+#### GenericTable (Generic/GenericTable.tsx)
+
+**Purpose:** Reusable data grid with full CRUD functionality.
+
+**Features:**
+- MUI X DataGrid v7 integration
+- Server-side pagination, sorting, filtering
+- Row editing (inline)
+- Bulk selection and delete
+- Toast notifications
+- Filter panel with field selection
+
+**Props:**
+```typescript
+interface GenericTableProps<T extends BaseEntity> {
+  entityName: string;
+  sliceSelector: (state: RootState) => EntitySliceState<T>;
+  fetchAction: AsyncThunk<...>;
+  updateAction: AsyncThunk<...>;
+  deleteAction: AsyncThunk<...>;
+  deleteByIdsAction?: AsyncThunk<...>;
+  setRefetchAction: (refetch: boolean) => Action;
+  loadColumnsFunction: (...) => Promise<GridColDef[]>;
+  filters: Filter[];
+  filterItems: FilterItem[];
+  setFilterItems: (items: FilterItem[]) => void;
+  extraQuery?: string;
+}
+```
+
+**Data Flow:**
+```
+1. Component mounts → loadColumnsFunction loads columns
+2. fetchAction dispatched with pagination/sort/filter query
+3. Data stored in Redux slice under entityName key
+4. DataGrid renders rows with server-side pagination
+5. Edit saves via updateAction
+6. Delete via deleteAction or deleteByIdsAction (bulk)
+```
+
+---
+
+### 4. Constructor Components (15 files)
+
+Components for the visual tour builder interface.
+
+| Component | Purpose | LOC |
+|-----------|---------|-----|
+| `CanvasElement.tsx` | Renders element on canvas with positioning | 62 |
+| `ElementEditorPanel.tsx` | Settings sidebar with tabs (General/CSS/Effects) | 592 |
+| `ConstructorToolbar.tsx` | Floating main constructor toolbar with mode, page, element, save, stage, exit, and collapse actions | ~490 |
+| `ConstructorControlsPanel.tsx` | Legacy/secondary controls panel for constructor actions | ~200 |
+| `ConstructorMenu.tsx` | Left menu with element types | ~150 |
+| `BackgroundSettingsEditor.tsx` | Image/video/audio background selection | ~100 |
+| `CreateTransitionForm.tsx` | Transition video creation form | ~80 |
+| `ElementEditorHeader.tsx` | Draggable header for editor panel | ~50 |
+| `PageSelector.tsx` | Tour page dropdown selector with ordinal labels and optional toolbar sizing class | ~60 |
+| `InteractionModeToggle.tsx` | Edit vs Interact mode toggle with compact toolbar layout | ~40 |
+| `MenuActionButton.tsx` | Reusable menu button | ~30 |
+| `AssetSelectCompact.tsx` | Asset dropdown selector | ~50 |
+| `CanvasBackground.tsx` | Background rendering (image/video) | ~80 |
+| `TransitionPreviewOverlay.tsx` | Video transition preview | ~100 |
+| `index.ts` | Barrel exports | ~20 |
+| `types.ts` | Constructor type definitions | ~50 |
+
+**ConstructorToolbar.tsx action layout:**
+- The left block contains the Edit/Interact mode toggle.
+- `Page actions` groups page selector, page reorder, new page, duplicate page,
+  delete page, and background controls. All page-level controls use consistent
+  40px control height and explicit vertical dividers.
+- `Elements actions` groups the Add Elements dropdown and element Copy/Paste
+  buttons. Copy is enabled only when an element is selected; Paste is enabled
+  only when the constructor-local element clipboard has content.
+- Save, Stage, Exit, and Collapse are kept in the final action group. Save and
+  Stage use fixed compact widths and reserve the timestamp subtitle row even
+  when no timestamp is available, so the action group remains vertically
+  aligned as save status changes.
+- Section labels are centered above their controls to distinguish page-level
+  copy/duplicate from element copy/paste.
+
+**Page management controls:**
+- `PageSelector.tsx` displays page labels with order prefixes so users can see
+  the current sequence directly in the dropdown.
+- Page move buttons call the constructor page reorder handler with `up` or
+  `down`; the handler persists the full ordered ID list via
+  `POST /api/tour_pages/reorder`.
+- Duplicate page saves the current dev page first, then calls
+  `POST /api/tour_pages/:id/duplicate`; the backend appends the new independent
+  page as the last page and regenerates page element IDs.
+- Delete page opens the constructor confirmation modal and then calls the same
+  `DELETE /api/tour_pages/:id` endpoint used by Pages & Transitions.
+- Buttons are disabled while their matching async action is saving, when the
+  user lacks the required permission, and at first/last page boundaries for
+  reorder.
+
+**Element clipboard controls:**
+- Element Copy/Paste lives in the main toolbar, not in the element editor panel,
+  so users can copy an element, switch pages, and paste it into another page.
+- The clipboard is session-local to the active constructor page instance and is
+  managed by `useConstructorElements`.
+- Paste appends a deep clone to the active page's inline
+  `ui_schema_json.elements[]` data. It preserves all settings, including
+  position, dimensions, links, navigation targets, transition fields, CSS
+  styles, and effects, while regenerating element and nested item IDs.
+
+**CanvasElement.tsx Architecture:**
+```typescript
+interface CanvasElementProps {
+  element: CanvasElementType;
+  isSelected: boolean;
+  isEditMode: boolean;
+  isDisabled?: boolean;
+  onClick: () => void;
+  onMouseDown?: (event: React.MouseEvent) => void;
+  resolveUrl?: (url: string | undefined) => string;
+}
+
+const CanvasElement: React.FC<CanvasElementProps> = ({
+  element, isSelected, isEditMode, isDisabled, onClick, onMouseDown, resolveUrl,
+}) => {
+  return (
+    <button
+      type='button'
+      data-constructor-element-id={element.id}
+      className='absolute'
+      style={{
+        left: `${element.xPercent}%`,
+        top: `${element.yPercent}%`,
+        transform: 'translate(-50%, -50%)',
+        background: 'transparent',
+        border: 'none',
+        padding: 0,
+        margin: 0,
+      }}
+      onMouseDown={isEditMode ? onMouseDown : undefined}
+      onClick={onClick}
+    >
+      <UiElementRenderer
+        element={element}
+        resolveUrl={resolveUrl}
+        isSelected={isSelected}
+        isEditMode={isEditMode}
+        isDisabled={isDisabled}
+      />
+    </button>
+  );
+};
+```
+
+**ElementEditorPanel Tabs:**
+
+| Tab | Section | Properties |
+|-----|---------|------------|
+| General | CommonSettingsSection | label, position, timing |
+| General | NavigationSettingsSection | type, target, transition |
+| General | TooltipSettingsSection | title, text, icon |
+| General | DescriptionSettingsSection | title, text, fonts, colors |
+| General | MediaSettingsSection | url, autoplay, loop, muted |
+| General | GallerySettingsSection | cards (image, title, link) |
+| General | CarouselSettingsSection | slides, navigation icons |
+| CSS | StyleSettingsSection | width, height, margin, padding, etc. |
+| Effects | EffectsSettingsSection | appear animation, hover (incl. hover reveal), focus, active |
+
+---
+
+### 5. ElementSettings Components (23 files)
+
+Settings panels for element configuration in the constructor.
+
+**Full-Size Variants:**
+- `CommonSettingsSection.tsx`
+- `NavigationSettingsSection.tsx`
+- `TooltipSettingsSection.tsx`
+- `DescriptionSettingsSection.tsx`
+- `MediaSettingsSection.tsx`
+- `GallerySettingsSection.tsx`
+- `CarouselSettingsSection.tsx`
+- `InfoPanelSettingsSection.tsx`
+- `StyleSettingsSection.tsx`
+- `EffectsSettingsSection.tsx`
+- `ElementSettingsTabs.tsx`
+
+**Compact Variants (for ElementEditorPanel):**
+- `CommonSettingsSectionCompact.tsx`
+- `NavigationSettingsSectionCompact.tsx`
+- `TooltipSettingsSectionCompact.tsx`
+- `DescriptionSettingsSectionCompact.tsx`
+- `MediaSettingsSectionCompact.tsx`
+- `GallerySettingsSectionCompact.tsx`
+- `GalleryCarouselSettingsSectionCompact.tsx` (shared gallery/carousel settings)
+- `CarouselSettingsSectionCompact.tsx`
+- `InfoPanelSettingsSectionCompact.tsx`
+- `StyleSettingsSectionCompact.tsx`
+- `EffectsSettingsSectionCompact.tsx`
+
+**Info Panel Settings:**
+- The constructor General tab renders `InfoPanelSettingsSectionCompact`.
+- `Open by default` writes `infoPanelOpenByDefault` to the element JSON.
+- Global and project element-default detail pages render the full `InfoPanelSettingsSection`, so Info Panel default state can be configured at platform, project, and instance scope.
+- Disabled Info Panels (`infoPanelDisabled`) do not open by click or by default state.
+
+**Supporting Files:**
+- `index.ts` - Barrel exports
+- `types.ts` - Type definitions and unit normalization helpers
+- `useElementSettingsForm.ts` - Form state management hook
+
+**Unit Normalization Helpers (types.ts):**
+
+The `types.ts` file provides helper functions for CSS value handling:
+
+```typescript
+// Extract numeric value from CSS value with unit
+extractNumericValue('24vw')     // '24'
+extractNumericValue('100px')   // '100'
+
+// Convert value to CSS value with unit (robust normalization)
+toUnitValue('24', 'vw')        // '24vw'
+toUnitValue('24vw', 'vw')      // '24vw' (preserved)
+toUnitValue('0', 'px')         // '0'    (no unit for zero)
+toUnitValue('calc(100%)', 'px') // 'calc(100%)' (CSS functions preserved)
+toUnitValue('10px 20px', 'px')  // '10px 20px' (complex values preserved)
+
+// Normalize number string (removes invalid chars)
+normalizeNumberString('24.5')   // '24.5'
+normalizeNumberString('abc')    // ''
+
+// Convert to optional trimmed value
+toOptionalTrimmed('')          // undefined
+toOptionalTrimmed('  value  ') // 'value'
+```
+
+**Edge Cases Handled by `toUnitValue`:**
+| Input | Output | Reason |
+|-------|--------|--------|
+| `"24"` | `"24px"` | Plain number → add unit |
+| `"24px"` | `"24px"` | Has unit → preserve |
+| `"0"` | `"0"` | Zero → no unit needed |
+| `"-10"` | `"-10px"` | Negative → add unit |
+| `".5"` | `"0.5rem"` | Decimal → add unit |
+| `"10px 20px"` | `"10px 20px"` | Complex → preserve |
+| `"calc(100% - 20px)"` | preserved | CSS function → preserve |
+| `"var(--spacing)"` | preserved | CSS variable → preserve |
+
+**Index Re-exports:**
+```typescript
+// ElementSettings/index.ts
+export { ElementSettingsTabsCompact } from './ElementSettingsTabs';
+export { StyleSettingsSectionCompact } from './StyleSettingsSectionCompact';
+export { EffectsSettingsSectionCompact } from './EffectsSettingsSectionCompact';
+export { extractNumericValue, toUnitValue, toOptionalTrimmed } from './types';
+// ... etc
+```
+
+---
+
+### 6. UiElements Components (16 files)
+
+Unified element rendering for WYSIWYG consistency between Constructor and Runtime.
+
+**Directory Structure:**
+```
+UiElements/
+├── UiElementRenderer.tsx           # Main entry point
+├── GalleryCarouselOverlay.tsx      # Fullscreen overlay for gallery/carousel and Info Panel media
+├── shared/
+│   └── useElementWrapperStyle.ts   # Shared styling hook
+├── elements/
+│   ├── NavigationElement.tsx       # Forward/back buttons
+│   ├── GalleryElement.tsx          # Image grid
+│   ├── TooltipElement.tsx          # Tooltip popup
+│   ├── DescriptionElement.tsx      # Styled text block
+│   ├── CarouselElement.tsx         # Image slideshow
+│   ├── LogoElement.tsx             # Logo display
+│   ├── SpotElement.tsx             # Hotspot indicator
+│   ├── VideoPlayerElement.tsx      # Video with controls
+│   ├── AudioPlayerElement.tsx      # Audio with controls
+│   └── PopupElement.tsx            # Popup trigger
+├── ElementPreview.tsx              # Palette preview (separate system)
+├── defaults.ts                     # Default values
+└── types.ts                        # Type definitions
+```
+
+#### UiElementRenderer.tsx
+
+**Purpose:** Unified entry point for rendering UI elements with consistent styling. Used by both CanvasElement (constructor) and RuntimeElement (presentation).
+
+**Architecture:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│  UiElementRenderer - unified styling + content               │
+│    ├── useElementWrapperStyle (shared hook)                  │
+│    └── Per-type components (10 files)                        │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│  CONSTRUCTOR: CanvasElement (position, selection, drag)      │
+│    └── UiElementRenderer                                     │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│  RUNTIME: RuntimeElement (position, effects)                 │
+│    └── UiElementRenderer                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Props:**
+```typescript
+interface UiElementRendererProps {
+  element: CanvasElement;
+  resolveUrl?: (url: string | undefined) => string;
+  // Constructor-specific props (optional)
+  isSelected?: boolean;
+  isEditMode?: boolean;
+  isDisabled?: boolean;
+}
+```
+
+#### useElementWrapperStyle Hook
+
+**Purpose:** Single source of truth for element wrapper styling. Ensures constructor and runtime render elements identically.
+
+```typescript
+interface UseElementWrapperStyleOptions {
+  element: CanvasElement;
+  isSelected?: boolean;   // Constructor only
+  isEditMode?: boolean;   // Constructor only
+  isDisabled?: boolean;   // Constructor only
+}
+
+interface ElementWrapperStyle {
+  className: string;      // Tailwind classes
+  style: CSSProperties;   // Inline styles from buildElementStyle
+}
+```
+
+#### Per-Type Element Components
+
+Each element type has a dedicated component that handles both wrapper styling and content:
+
+| Component | Element Type | Rendering |
+|-----------|--------------|-----------|
+| `NavigationElement` | `navigation_next/prev` | Icon image or text label |
+| `TooltipElement` | `tooltip` | Icon or title/text popup |
+| `DescriptionElement` | `description` | Icon or styled title/text block |
+| `VideoPlayerElement` | `video_player` | `<video>` with controls |
+| `AudioPlayerElement` | `audio_player` | `<audio>` with controls |
+| `GalleryElement` | `gallery` | 3-column image grid |
+| `CarouselElement` | `carousel` | Slides with dots and nav icons |
+| `LogoElement` | `logo` | Icon image or text |
+| `SpotElement` | `spot` | Icon or animated pulse circle |
+| `PopupElement` | `popup` | Text label |
+
+**Per-Type Component Interface:**
+```typescript
+interface ElementComponentProps {
+  element: CanvasElement;
+  resolveUrl?: (url: string | undefined) => string;
+  className: string;      // From useElementWrapperStyle
+  style: CSSProperties;   // From useElementWrapperStyle
+}
+```
+
+---
+
+### 7. Offline/PWA Components (4 files)
+
+| Component | Purpose |
+|-----------|---------|
+| `OfflineStatusIndicator.tsx` | Shows online/offline status |
+| `DownloadProgressPanel.tsx` | Shows download progress for PWA caching |
+| `OfflineToggle.tsx` | Enable/disable offline mode |
+| `StorageUsageDisplay.tsx` | Shows storage quota usage |
+
+---
+
+### 8. Uploaders (1 file)
+
+#### UploadService.js
+
+**Purpose:** File upload service with chunked uploads and MIME type validation.
+
+**Location:** `frontend/src/components/Uploaders/UploadService.js`
+
+**Key Features:**
+- Single-file upload via `upload()`
+- Chunked upload via `uploadChunked()` for large files
+- MIME type validation with extension fallback
+- Progress callbacks and abort support
+
+**MIME Type Validation:**
+
+```javascript
+const VALID_MIME_TYPES = {
+  image: {
+    prefixes: ['image/'],
+    extensions: ['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'bmp', 'ico'],
+  },
+  video: {
+    prefixes: ['video/'],
+    extensions: ['mp4', 'webm', 'mov', 'avi', 'mkv', 'm4v', 'ogv'],
+  },
+  audio: {
+    prefixes: ['audio/'],
+    extensions: ['mp3', 'wav', 'ogg', 'aac', 'm4a', 'flac', 'weba'],
+  },
+};
+```
+
+**Validation Schema:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `assetType` | string | Asset type: `'image'`, `'video'`, or `'audio'` |
+| `image` | boolean | Legacy: Must be an image |
+| `video` | boolean | Legacy: Must be a video |
+| `audio` | boolean | Legacy: Must be audio |
+| `size` | number | Max file size in bytes |
+| `formats` | string[] | Allowed file extensions |
+
+**Usage:**
+```javascript
+// Chunked upload with validation
+const result = await FileUploader.uploadChunked(
+  'assets/project-id',
+  file,
+  { assetType: 'image' },  // Validation schema
+  {
+    chunkSize: 5 * 1024 * 1024,
+    maxRetries: 3,
+    signal: abortController.signal,
+    onProgress: (percent) => console.log(`${percent}%`),
+    onStatus: (status) => console.log(status),
+  }
+);
+```
+
+See [Asset Upload & Variants](../../documentation/asset-upload-variants.md) for complete upload flow documentation.
+
+---
+
+### 9. Layout Components
+
+#### NavBar.tsx
+
+**Purpose:** Top navigation bar with responsive menu.
+
+**Features:**
+- Fixed position with scroll shadow
+- Mobile menu toggle
+- Integrates with `NavBarMenuList` for menu items
+- Theme-aware background
+
+```typescript
+type Props = {
+  menu: MenuNavBarItem[];
+  className: string;
+  children: ReactNode;
+};
+
+export default function NavBar({ menu, className, children }: Props) {
+  const [isMenuNavBarActive, setIsMenuNavBarActive] = useState(false);
+  const [isScrolled, setIsScrolled] = useState(false);
+  // ...
+}
+```
+
+#### AsideMenu.tsx
+
+**Purpose:** Sidebar navigation with mobile responsiveness.
+
+```typescript
+type Props = {
+  menu: MenuAsideItem[];
+  isAsideMobileExpanded: boolean;
+  isAsideLgActive: boolean;
+  onAsideLgClose: () => void;
+};
+```
+
+#### SectionMain.tsx
+
+**Purpose:** Main content wrapper with consistent padding.
+
+#### FooterBar.tsx
+
+**Purpose:** Footer with copyright.
+
+---
+
+### 10. Standalone Components (~50 files)
+
+Key standalone components used throughout the application.
+
+#### BaseButton.tsx
+
+**Purpose:** Universal button component with variants.
+
+```typescript
+type Props = {
+  label?: string;
+  /** Optional subtitle displayed below the label in smaller text */
+  subtitle?: string;
+  icon?: string;
+  iconSize?: string | number;
+  href?: string;
+  target?: string;
+  type?: string;
+  color?: ColorButtonKey;
+  className?: string;
+  small?: boolean;
+  outline?: boolean;
+  active?: boolean;
+  disabled?: boolean;
+  roundedFull?: boolean;
+  onClick?: (e: React.MouseEvent) => void;
+};
+```
+
+**Features:**
+- Link or button rendering
+- Icon support with BaseIcon
+- Color variants via `getButtonColor`
+- Theme-aware corners from Redux
+- **Subtitle support** for secondary text (e.g., timestamps)
+
+**Subtitle Usage:**
+```typescript
+// Show publish timestamp below button label
+<BaseButton
+  label="Publish to Production"
+  subtitle={lastPublishedAt ? `Last: ${relativeTimestamp(lastPublishedAt)}` : undefined}
+  color="success"
+  onClick={handlePublish}
+/>
+// Renders:
+// ┌──────────────────────────┐
+// │  Publish to Production   │
+// │    Last: 5 min ago       │  ← smaller, 80% opacity
+// └──────────────────────────┘
+```
+
+#### CardBox.tsx
+
+**Purpose:** Card container with consistent styling.
+
+```typescript
+type Props = {
+  rounded?: string;
+  flex?: string;
+  className?: string;
+  hasComponentLayout?: boolean;
+  hasTable?: boolean;
+  isHoverable?: boolean;
+  isModal?: boolean;
+  children?: ReactNode;
+  footer?: ReactNode;
+};
+```
+
+#### FormField.tsx
+
+**Purpose:** Form field wrapper with label and help text.
+
+**Features:**
+- Multi-column grid support (2-3 children)
+- Icon prefix support
+- Theme-aware styling
+
+#### RuntimePresentation.tsx (18.5KB)
+
+**Purpose:** Full-screen tour playback component.
+
+**Hooks Used:**
+- `usePageDataLoader` - Load page data
+- `usePreloadOrchestrator` - Asset preloading
+- `usePageSwitch` - Page navigation
+- `useTransitionPlayback` - Video transitions
+- `useBackgroundTransition` - Background changes
+
+**Features:**
+- Fullscreen mode
+- Keyboard navigation (ArrowLeft/Right, Escape)
+- Touch gestures
+- Transition videos
+- Element effects (appear animation, hover)
+
+#### RuntimeElement.tsx
+
+**Purpose:** Element wrapper for runtime with interactive effects. Delegates styling and content to UiElementRenderer.
+
+```typescript
+interface RuntimeElementProps {
+  element: any;
+  onClick: () => void;
+  resolveUrl?: (url: string | undefined) => string;
+}
+
+const RuntimeElement: React.FC<RuntimeElementProps> = ({
+  element,
+  onClick,
+  resolveUrl,
+}) => {
+  // Extract effect properties for hover/focus/active states
+  const { effectStyle, eventHandlers } = useElementEffects(effectProperties);
+
+  // Build position style with effects merged
+  let positionStyle: React.CSSProperties = {
+    left: `${xPercent}%`,
+    top: `${yPercent}%`,
+    transform: `translate(-50%, -50%)${rotation ? ` rotate(${rotation}deg)` : ''}`,
+  };
+
+  // Merge effect styles and animations...
+
+  return (
+    <div
+      className='absolute cursor-pointer'
+      style={positionStyle}
+      onClick={onClick}
+      tabIndex={0}
+      {...eventHandlers}
+    >
+      <UiElementRenderer element={element} resolveUrl={resolveUrl} />
+    </div>
+  );
+};
+```
+
+#### TourFlowManager.tsx (17KB)
+
+**Purpose:** Page and transition management interface.
+
+**Features:**
+- Page list with thumbnails
+- Drag-and-drop reordering
+- Transition configuration
+- Page CRUD operations
+- Sort order management
+
+#### Other Notable Components
+
+| Component | Purpose |
+|-----------|---------|
+| `BaseIcon.tsx` | MDI icon wrapper |
+| `ImageField.tsx` | Image display with fallback |
+| `Search.tsx` | Global search input |
+| `SectionTitleLineWithButton.tsx` | Section header with action |
+| `DataGridMultiSelect.tsx` | Multi-select for DataGrid |
+| `ListActionsPopover.tsx` | Row actions dropdown |
+| `Divider.tsx` | Horizontal divider |
+| `NotificationBar.tsx` | Toast notification wrapper |
+| `OverlayLayer.tsx` | Modal overlay background |
+| `PillTag.tsx` | Tag/badge component |
+| `UserAvatar.tsx` | User avatar display |
+
+---
+
+## Component Patterns
+
+### 1. Factory Pattern
+
+**Tables:** 13 entity tables generated from configuration.
+**Columns:** 13 column configs generated from metadata.
+
+**Benefit:** ~1500 LOC reduced to ~300 LOC configuration.
+
+### 2. Theme-Aware Styling
+
+Components read theme values from Redux:
+
+```typescript
+const corners = useAppSelector((state) => state.style.corners);
+const cardsStyle = useAppSelector((state) => state.style.cardsStyle);
+const iconsColor = useAppSelector((state) => state.style.iconsColor);
+const bgColor = useAppSelector((state) => state.style.bgLayoutColor);
+const focusRing = useAppSelector((state) => state.style.focusRingColor);
+```
+
+### 3. Composition Pattern
+
+Complex components compose smaller ones:
+
+```
+RuntimePresentation
+├── RuntimeElement (×N)
+│   └── UiElementRenderer
+│       └── Per-type Element (NavigationElement, GalleryElement, etc.)
+├── CanvasBackground
+└── TransitionVideoOverlay
+
+Constructor Page
+├── CanvasElement (×N)
+│   └── UiElementRenderer
+│       └── Per-type Element (NavigationElement, GalleryElement, etc.)
+├── CanvasBackground
+└── ElementEditorPanel
+```
+
+### 4. Compact Variants
+
+Settings sections have two variants:
+- **Full:** Standalone use with labels
+- **Compact:** Embedded use with compact layout
+
+### 5. URL Resolution Pattern
+
+Components accept optional URL resolver for blob URLs:
+
+```typescript
+interface Props {
+  resolveUrl?: (url: string | undefined) => string;
+}
+
+// Usage
+const resolve = resolveUrl ?? resolveAssetPlaybackUrl;
+const src = resolve(element.iconUrl);
+```
+
+---
+
+## File Count Summary
+
+| Category | Files | LOC (est.) |
+|----------|-------|------------|
+| Entity Components | 52 | ~1000 |
+| Factory Components | 2 | ~420 |
+| Generic Components | 2 | ~500 |
+| Constructor | 15 | ~1600 |
+| ElementSettings | 23 | ~2200 |
+| UiElements | 16 | ~750 |
+| Offline | 5 | ~350 |
+| Layout | 10 | ~500 |
+| Standalone | ~50 | ~4000 |
+| **Total** | **~175** | **~11,300** |
+
+---
+
+## Component Dependencies
+
+```
+┌─────────────────────────────────────────────────────┐
+│                     Pages                           │
+│   (dashboard.tsx, assets-list.tsx, constructor.tsx) │
+└─────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────┐
+│              Entity Components                      │
+│   (TableUsers, TableAssets, TableProjects, ...)     │
+│                                                     │
+│   Uses: createTableComponent + configBuilderFactory │
+└─────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────┐
+│              GenericTable                           │
+│   MUI X DataGrid + filters + pagination + editing   │
+│                                                     │
+│   Uses: CardBox, BaseButton, Formik                 │
+└─────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────┐
+│              Base Components                        │
+│   BaseButton, CardBox, FormField, BaseIcon          │
+│                                                     │
+│   Uses: Redux style selectors, Tailwind CSS         │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Styling System
+
+### Tailwind CSS Classes
+
+Components use Tailwind utilities with theme values:
+
+```typescript
+const componentClass = [
+  `flex dark:border-dark-700 dark:bg-dark-900`,
+  corners !== 'rounded-full' ? corners : 'rounded-3xl',
+  cardsStyle,
+];
+```
+
+### Dark Mode
+
+All components support dark mode via:
+- `dark:` prefix classes
+- `darkMode` state from Redux
+- Applied at layout level
+
+### Dynamic Styling
+
+Constructor elements use inline styles from `buildElementStyle`:
+
+```typescript
+import { buildElementStyle } from '../../lib/elementStyles';
+
+const style = buildElementStyle(element);
+// Returns: { width, height, backgroundColor, color, fontSize, ... }
+```
+
+---
+
+## Best Practices
+
+### 1. Use Factories for Entity Components
+
+```typescript
+// Good - 23 LOC
+const TableUsers = createTableComponent<User>({ ... });
+
+// Avoid - 400+ LOC of boilerplate
+```
+
+### 2. Theme-Aware Styling
+
+```typescript
+// Good - reads from Redux
+const corners = useAppSelector((state) => state.style.corners);
+
+// Avoid - hardcoded
+className="rounded-lg"
+```
+
+### 3. URL Resolution for Assets
+
+```typescript
+// Good - supports preloaded blob URLs
+<img src={resolve(element.iconUrl)} />
+
+// Avoid - only works online
+<img src={element.iconUrl} />
+```
+
+### 4. Compact Variants for Embedded Use
+
+```typescript
+// Good - use compact in panels
+<CommonSettingsSectionCompact {...props} />
+
+// Avoid - full variant in compact space
+<CommonSettingsSection {...props} />
+```
+
+---
+
+## Related Documentation
+
+- [Frontend Architecture](./frontend-architecture.md) - Overall frontend structure
+- [Pages Module](./pages-module.md) - Page components
+- [Hooks Reference](./hooks-reference.md) - Custom hooks
+- [Constructor Page Editor](./constructor-page-editor.md) - Visual builder
+- [Runtime Presentation](./runtime-presentation.md) - Tour playback
diff --git a/frontend/docs/config-module.md b/frontend/docs/config-module.md
new file mode 100644
index 0000000..8787615
--- /dev/null
+++ b/frontend/docs/config-module.md
@@ -0,0 +1,1021 @@
+# Frontend Config Module
+
+## Overview
+
+The Config module provides **centralized configuration** for the frontend application across multiple layers: build tooling, runtime settings, navigation menus, offline/PWA functionality, and asset preloading.
+
+**Location:**
+- Root configs: `frontend/*.config.*`
+- Runtime configs: `frontend/src/config/`, `frontend/src/config.ts`, `frontend/src/menuAside.ts`, `frontend/src/menuNavBar.ts`
+
+**Total Files:** 12 config-related files
+
+---
+
+## Architecture
+
+```
+frontend/
+├── next.config.mjs        (44 LOC)   # Next.js configuration
+├── tailwind.config.js     (114 LOC)  # Tailwind CSS theming
+├── postcss.config.js      (8 LOC)    # PostCSS plugins
+├── prettier.config.js     (12 LOC)   # Code formatting
+├── tsconfig.json          (30 LOC)   # TypeScript compiler
+├── .eslintrc.cjs          (50 LOC)   # ESLint rules
+├── .eslintignore          (3 LOC)    # ESLint exclusions
+├── package.json           (84 LOC)   # NPM scripts & deps
+│
+└── src/
+    ├── config.ts           (20 LOC)   # Runtime app config
+    ├── menuAside.ts        (42 LOC)   # Sidebar navigation
+    ├── menuNavBar.ts       (51 LOC)   # Top navbar menus
+    ├── interfaces/index.ts (123 LOC)  # Menu type definitions
+    │
+    └── config/
+        ├── offline.config.ts   (52 LOC)   # PWA/offline settings
+        └── preload.config.ts   (94 LOC)   # Asset preloading settings
+```
+
+---
+
+## Root Configuration Files
+
+### 1. Next.js Configuration (`next.config.mjs`)
+
+**Purpose:** Configure Next.js build and runtime behavior.
+
+**Lines:** 44 LOC
+
+```javascript
+import withSerwistInit from '@serwist/next';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const output = process.env.NEXT_OUTPUT || undefined;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+const withSerwist = withSerwistInit({
+  swSrc: 'src/sw.ts',
+  swDest: 'public/sw.js',
+  disable: isDevelopment,
+  maximumFileSizeToCacheInBytes: 5 * 1024 * 1024,
+});
+
+const nextConfig = {
+  trailingSlash: true,
+  distDir: isDevelopment ? '.next' : 'build',
+  outputFileTracingRoot: __dirname,
+  output,
+  basePath: '',
+  devIndicators: {
+    position: 'bottom-left',
+  },
+  typescript: {
+    ignoreBuildErrors: false,
+  },
+  eslint: {
+    ignoreDuringBuilds: false,
+  },
+  images: {
+    unoptimized: true,
+    remotePatterns: [
+      { protocol: 'https', hostname: '**' },
+    ],
+    localPatterns: [
+      { pathname: '/api/**' },
+    ],
+  },
+};
+
+export default withSerwist(nextConfig);
+```
+
+#### Configuration Options
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| `trailingSlash` | `true` | URLs end with `/` for consistent routing |
+| `distDir` | `.next` in development, `build` in production | Keeps Turbopack dev artifacts separate from production `next build` output |
+| `output` | `undefined` by default, env override supported | Default VM build runs as a Next.js server |
+| `images.unoptimized` | `true` | Disable image optimization (custom asset handling) |
+| `typescript.ignoreBuildErrors` | `false` | Fail build on TS errors |
+| `eslint.ignoreDuringBuilds` | `false` | Fail build on lint errors |
+
+#### Serwist (PWA) Integration
+
+```javascript
+withSerwistInit({
+  swSrc: 'src/sw.ts',      // Service worker source
+  swDest: 'public/sw.js',  // Compiled output
+  disable: isDevelopment,  // Dev: no SW
+})
+```
+
+`public/sw.js` is generated by the build and is ignored by git. The source of
+truth is `src/sw.ts`. `next-env.d.ts` is also generated by Next.js and ignored
+to avoid local diffs when build/type generation updates its route type
+reference.
+
+---
+
+### 2. Tailwind CSS Configuration (`tailwind.config.js`)
+
+**Purpose:** Custom theme, colors, animations, and plugins.
+
+**Lines:** 114 LOC
+
+#### Content Scanning
+```javascript
+content: [
+  './src/**/*.{js,ts,jsx,tsx}',
+],
+```
+
+#### Dark Mode
+```javascript
+darkMode: 'class',  // Toggle via class (not media query)
+```
+
+#### Custom Theme Extensions
+
+```javascript
+theme: {
+  extend: {
+    // Custom fonts
+    fontFamily: {
+      'instrument': ['"Instrument Sans Variable"', 'sans-serif'],
+      'instrument-condensed': ['"Instrument Sans Variable"', 'sans-serif'],
+    },
+
+    // Z-index for overlays
+    zIndex: { '-1': '-1' },
+
+    // Flex utilities
+    flexGrow: { 5: '5' },
+
+    // Max heights for menus/modals
+    maxHeight: {
+      'screen-menu': 'calc(100vh - 3.5rem)',
+      modal: 'calc(100vh - 160px)',
+    },
+
+    // Transition properties
+    transitionProperty: {
+      position: 'right, left, top, bottom, margin, padding',
+      textColor: 'color',
+    },
+
+    // Animations
+    keyframes: {
+      'fade-out': { from: { opacity: 1 }, to: { opacity: 0 } },
+      'fade-in': { from: { opacity: 0 }, to: { opacity: 1 } },
+    },
+    animation: {
+      'fade-out': 'fade-out 250ms ease-in-out',
+      'fade-in': 'fade-in 250ms ease-in-out',
+    },
+
+    // Custom color palette
+    colors: {
+      dark: {
+        900: '#131618',
+        800: '#21242A',
+        700: '#2C2F36',
+        600: '#9CA3AF',
+        500: '#CBD5E1',
+      },
+      green: { text: '#45B26B' },
+      'pavitra': {
+        'blue': '#0162FD',
+        'green': '#00B448',
+        'orange': '#FFAA00',
+        'red': '#F20041',
+        900: '#14142A',
+        800: '#4E4B66',
+        700: '#6E7191',
+        600: '#A0A3BD',
+        500: '#D9DBE9',
+        400: '#EFF0F6',
+        300: '#F7F7FC',
+      },
+    },
+
+    // Extended border radius
+    borderRadius: {
+      '3xl': '2rem',
+    },
+  },
+}
+```
+
+#### Custom Plugins
+
+```javascript
+plugins: [
+  require('@tailwindcss/forms'),        // Form styling
+  require('@tailwindcss/typography'),   // Prose content
+
+  // Custom scrollbar utility
+  plugin(function ({ matchUtilities, theme }) {
+    matchUtilities({
+      'aside-scrollbars': (value) => ({
+        scrollbarWidth: 'thin',
+        scrollbarColor: `${theme(`colors.${color}.${thumb}`)} ${theme(`colors.${color}.${track}`)}`,
+        '&::-webkit-scrollbar': { width: '8px', height: '8px' },
+        '&::-webkit-scrollbar-track': { backgroundColor: theme(`colors.${color}.${track}`) },
+        '&::-webkit-scrollbar-thumb': { borderRadius: '0.25rem', backgroundColor: theme(`colors.${color}.${thumb}`) },
+      }),
+    }, { values: theme('asideScrollbars') });
+  }),
+]
+```
+
+---
+
+### 3. PostCSS Configuration (`postcss.config.js`)
+
+**Purpose:** CSS processing pipeline.
+
+**Lines:** 8 LOC
+
+```javascript
+module.exports = {
+  plugins: {
+    'postcss-import': {},       // @import resolution
+    'tailwindcss/nesting': {},  // CSS nesting support
+    tailwindcss: {},            // Tailwind processing
+    autoprefixer: {},           // Vendor prefixes
+  },
+}
+```
+
+---
+
+### 4. Prettier Configuration (`prettier.config.js`)
+
+**Purpose:** Code formatting rules.
+
+**Lines:** 12 LOC
+
+```javascript
+module.exports = {
+  semi: false,              // No semicolons
+  singleQuote: true,        // Single quotes
+  printWidth: 100,          // Line width
+  trailingComma: 'es5',     // ES5-compatible trailing commas
+  arrowParens: 'always',    // Always wrap arrow params: (x) => x
+  tabWidth: 2,              // 2-space indentation
+  useTabs: false,           // Spaces, not tabs
+  quoteProps: 'as-needed',  // Quote object keys only when needed
+  jsxSingleQuote: false,    // Double quotes in JSX
+  bracketSpacing: true,     // Spaces in object literals
+  bracketSameLine: false,   // JSX closing bracket on new line
+}
+```
+
+---
+
+### 5. TypeScript Configuration (`tsconfig.json`)
+
+**Purpose:** TypeScript compiler options.
+
+**Lines:** 30 LOC
+
+```json
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}
+```
+
+#### Key Settings
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| `strict` | `false` | Relaxed type checking (legacy) |
+| `noEmit` | `true` | Next.js handles compilation |
+| `incremental` | `true` | Faster rebuilds |
+| `isolatedModules` | `true` | Required for Next.js |
+
+---
+
+### 6. ESLint Configuration (`.eslintrc.cjs`)
+
+**Purpose:** Code linting rules.
+
+**Lines:** 50 LOC
+
+```javascript
+module.exports = {
+  extends: [
+    'next/core-web-vitals',
+    'plugin:@typescript-eslint/recommended',
+    'eslint-config-prettier',
+  ],
+  plugins: ['import'],
+  settings: {
+    'import/resolver': {
+      typescript: { project: ['./tsconfig.json'] },
+    },
+  },
+  rules: {
+    'react/no-children-prop': 'off',
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-unused-vars': 'off',
+    '@typescript-eslint/ban-types': 'off',
+    'react-hooks/exhaustive-deps': 'off',
+    'import/named': 'error',
+    'import/no-duplicates': 'error',
+    'import/no-unresolved': 'error',
+    'no-console': 'error',  // Use logger instead
+  },
+  overrides: [
+    // Allow console in logger utility
+    { files: ['src/lib/logger.ts'], rules: { 'no-console': 'off' } },
+    // Allow console in service worker
+    { files: ['src/sw.ts'], rules: { 'no-console': 'off' } },
+    // Allow console in API routes
+    { files: ['src/pages/api/**/*.ts'], rules: { 'no-console': 'off' } },
+  ],
+};
+```
+
+#### Key Rules
+
+| Rule | Setting | Purpose |
+|------|---------|---------|
+| `no-console` | `error` | Force use of `logger` utility |
+| `import/no-unresolved` | `error` | Catch missing imports |
+| `import/no-duplicates` | `error` | No duplicate imports |
+
+---
+
+## Source Configuration Files
+
+### 1. Runtime App Config (`src/config.ts`)
+
+**Purpose:** Application-wide runtime settings.
+
+**Lines:** 20 LOC
+
+```typescript
+export const hostApi =
+  process.env.NODE_ENV === 'development' && !process.env.NEXT_PUBLIC_BACK_API
+    ? 'http://localhost'
+    : '';
+
+export const portApi =
+  process.env.NODE_ENV === 'development' && !process.env.NEXT_PUBLIC_BACK_API
+    ? 3000
+    : '';
+
+export const baseURLApi = `${hostApi}${portApi ? `:${portApi}` : ``}/api`;
+
+export const localStorageDarkModeKey = 'darkMode';
+
+export const localStorageStyleKey = 'style';
+
+export const containerMaxW = 'xl:max-w-full xl:mx-auto 2xl:mx-20';
+
+export const appTitle = 'Shimahara Visual';
+
+export const getPageTitle = (currentPageTitle: string) =>
+  `${currentPageTitle} — ${appTitle}`;
+```
+
+#### Exports
+
+| Export | Type | Purpose | Used By |
+|--------|------|---------|---------|
+| `baseURLApi` | `string` | API base URL | `_app.tsx`, `UploadService.js` |
+| `localStorageDarkModeKey` | `string` | Dark mode storage key | `styleSlice.ts` |
+| `localStorageStyleKey` | `string` | Style storage key | `styleSlice.ts` |
+| `containerMaxW` | `string` | Container max-width classes | `NavBar.tsx`, `SectionMain.tsx`, `FooterBar.tsx` |
+| `appTitle` | `string` | Application name | Various pages |
+| `getPageTitle` | `function` | Generate page title | All pages (30+ files) |
+
+---
+
+### 2. Sidebar Menu Config (`src/menuAside.ts`)
+
+**Purpose:** Sidebar navigation items.
+
+**Lines:** 42 LOC
+
+```typescript
+import * as icon from '@mdi/js';
+import { MenuAsideItem } from './interfaces';
+
+const menuAside: MenuAsideItem[] = [
+  {
+    href: '/dashboard',
+    icon: icon.mdiViewDashboardOutline,
+    label: 'Dashboard',
+  },
+  {
+    href: '/projects/projects-list',
+    label: 'Projects',
+    icon: icon.mdiFolder,
+    permissions: 'READ_PROJECTS',
+  },
+  {
+    href: '/element-type-defaults',
+    label: 'Element Defaults',
+    icon: icon.mdiPaletteSwatch,
+    permissions: 'READ_PAGE_ELEMENTS',
+  },
+  {
+    href: '/users/users-list',
+    label: 'Users',
+    icon: icon.mdiAccountGroup,
+    permissions: 'READ_USERS',
+  },
+  {
+    href: '/profile',
+    label: 'Profile',
+    icon: icon.mdiAccountCircle,
+  },
+  {
+    href: swaggerDocsUrl,
+    target: '_blank',
+    label: 'Swagger',
+    icon: icon.mdiFileCode,
+    permissions: 'READ_API_DOCS',
+  },
+];
+
+export default menuAside;
+```
+
+#### Menu Item Structure
+
+```typescript
+type MenuAsideItem = {
+  label: string;                    // Display text
+  icon?: string;                    // MDI icon path
+  href?: string;                    // Navigation URL
+  target?: string;                  // Link target (_blank, etc.)
+  color?: ColorButtonKey;           // Button color
+  isLogout?: boolean;               // Logout action
+  withDevider?: boolean;            // Show divider
+  menu?: MenuAsideItem[];           // Sub-menu items
+  permissions?: string | string[];  // Required permission(s)
+};
+```
+
+---
+
+### 3. Navbar Menu Config (`src/menuNavBar.ts`)
+
+**Purpose:** Top navigation bar items.
+
+**Lines:** 51 LOC
+
+```typescript
+import { mdiAccount, mdiLogout, mdiThemeLightDark } from '@mdi/js';
+import { MenuNavBarItem } from './interfaces';
+
+const menuNavBar: MenuNavBarItem[] = [
+  {
+    isCurrentUser: true,
+    menu: [
+      { icon: mdiAccount, label: 'My Profile', href: '/profile' },
+      { isDivider: true },
+      { icon: mdiLogout, label: 'Log Out', isLogout: true },
+    ],
+  },
+  {
+    icon: mdiThemeLightDark,
+    label: 'Light/Dark',
+    isDesktopNoLabel: true,
+    isToggleLightDark: true,
+  },
+  {
+    icon: mdiLogout,
+    label: 'Log out',
+    isDesktopNoLabel: true,
+    isLogout: true,
+  },
+];
+
+export const webPagesNavBar = [];
+
+export default menuNavBar;
+```
+
+#### Menu Item Structure
+
+```typescript
+type MenuNavBarItem = {
+  label?: string;               // Display text
+  icon?: string;                // MDI icon path
+  href?: string;                // Navigation URL
+  target?: string;              // Link target
+  isDivider?: boolean;          // Render as divider
+  isLogout?: boolean;           // Logout action
+  isDesktopNoLabel?: boolean;   // Icon-only on desktop
+  isToggleLightDark?: boolean;  // Dark mode toggle
+  isCurrentUser?: boolean;      // User dropdown
+  menu?: MenuNavBarItem[];      // Sub-menu items
+};
+```
+
+---
+
+### 4. Offline Config (`src/config/offline.config.ts`)
+
+**Purpose:** PWA offline mode and IndexedDB settings.
+
+**Lines:** 52 LOC
+
+```typescript
+export const OFFLINE_CONFIG = {
+  // IndexedDB
+  dbName: 'TourBuilderOffline',
+  dbVersion: 1,
+
+  // Cache names (for Cache API)
+  cacheNames: {
+    static: 'tour-builder-static-v1',
+    dynamic: 'tour-builder-dynamic-v1',
+    assets: 'tour-builder-assets-v1',
+  },
+
+  // Events (EventEmitter event names)
+  events: {
+    preloadStart: 'asset-preload-start',
+    preloadProgress: 'asset-preload-progress',
+    preloadComplete: 'asset-preload-complete',
+    preloadError: 'asset-preload-error',
+    projectDownloadProgress: 'project-download-progress',
+    projectDownloadComplete: 'project-download-complete',
+    queueUpdate: 'queue-update',
+  },
+
+  // Service worker settings
+  serviceWorker: {
+    scope: '/',
+    updateInterval: 60 * 60 * 1000, // 1 hour
+  },
+
+  // Storage settings
+  storage: {
+    cacheApiMaxSize: 5 * 1024 * 1024,   // 5MB - use Cache API
+    indexedDbMinSize: 5 * 1024 * 1024,  // 5MB+ - use IndexedDB
+  },
+
+  // Retry settings
+  retry: {
+    maxRetries: 3,
+    backoffMs: 1000,
+    maxBackoffMs: 30000,
+  },
+} as const;
+
+export type OfflineConfig = typeof OFFLINE_CONFIG;
+```
+
+#### Usage
+
+```typescript
+import { OFFLINE_CONFIG } from '../config/offline.config';
+
+// Service worker cache name
+const cache = await caches.open(OFFLINE_CONFIG.cacheNames.assets);
+
+// Storage size threshold
+if (fileSize < OFFLINE_CONFIG.storage.cacheApiMaxSize) {
+  // Store in Cache API
+} else {
+  // Store in IndexedDB
+}
+```
+
+#### Consumers
+
+| File | Usage |
+|------|-------|
+| `sw.ts` | Cache names, storage settings |
+| `StorageManager.ts` | Storage thresholds |
+| `DownloadManager.ts` | Retry settings |
+| `DownloadEventBus.ts` | Event names |
+| `usePreloadOrchestrator.ts` | Event names |
+| `usePreloadProgress.ts` | Event names |
+| `useOfflineMode.ts` | Cache names |
+| `DownloadContext.tsx` | Events, retries |
+| `offlineDb/schema.ts` | DB name, version |
+
+---
+
+### 5. Preload Config (`src/config/preload.config.ts`)
+
+**Purpose:** Asset preloading priorities and queue settings.
+
+**Lines:** 94 LOC
+
+```typescript
+export const PRELOAD_CONFIG = {
+  // Queue settings
+  maxConcurrentDownloads: 3,
+  maxRetries: 3,
+  retryDelayMs: 1000,
+
+  // Size thresholds
+  largeFileThreshold: 5 * 1024 * 1024,    // 5MB -> use IndexedDB
+  videoChunkSize: 5 * 1024 * 1024,        // 5MB chunks
+  initialVideoBufferSeconds: 5,
+
+  // Priority weights (higher = load first)
+  priority: {
+    currentPage: 1000,
+    neighborBase: 500,
+    assetType: {
+      transition: 150,  // Highest - needed on navigation click
+      image: 100,       // Backgrounds load during transition
+      audio: 50,
+      video: 30,
+    } as Record<string, number>,
+    variant: {
+      thumbnail: 50,
+      preview: 40,
+      webp: 35,
+      mp4_low: 20,
+      mp4_high: 10,
+      original: 5,
+    } as Record<string, number>,
+    linkCountMultiplier: 10,
+    maxLinkBonus: 50,
+  },
+
+  // Storage
+  storage: {
+    warningPercent: 80,
+    criticalPercent: 95,
+    minFreeBuffer: 50 * 1024 * 1024,  // 50MB
+  },
+
+  // Auto-cleanup timeouts
+  autoRemove: {
+    completedMs: 3000,
+    errorMs: 10000,
+  },
+
+  // Neighbor graph traversal
+  neighborGraph: {
+    maxDepth: 1,  // Only preload immediate neighbors
+    constructorMaxDepth: 1,
+  },
+
+  // Asset URL field names in element content_json
+  assetFields: {
+    all: [
+      'iconUrl', 'imageUrl', 'mediaUrl', 'videoUrl', 'audioUrl',
+      'transitionVideoUrl', 'backgroundImageUrl', 'reverseVideoUrl',
+      'carouselPrevIconUrl', 'carouselNextIconUrl', 'src', 'url',
+      'poster', 'thumbnail',
+    ] as const,
+    images: [
+      'iconUrl', 'imageUrl', 'backgroundImageUrl',
+      'carouselPrevIconUrl', 'carouselNextIconUrl', 'src',
+    ] as const,
+    nested: ['galleryCards', 'carouselSlides'] as const,
+    nestedUrlFields: ['imageUrl', 'videoUrl'] as const,
+  },
+} as const;
+
+export type PreloadConfig = typeof PRELOAD_CONFIG;
+```
+
+#### Priority System
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Priority Calculation                     │
+│                                                             │
+│  Base Priority:                                             │
+│    currentPage: 1000 (loading current page assets)          │
+│    neighborBase: 500 (adjacent pages)                       │
+│                                                             │
+│  Asset Type Bonus:                                          │
+│    transition: +150  (needed immediately)                   │
+│    image: +100       (backgrounds)                          │
+│    audio: +50        (background audio)                     │
+│    video: +30        (content videos)                       │
+│                                                             │
+│  Variant Bonus:                                             │
+│    thumbnail: +50    (quick previews)                       │
+│    preview: +40      (medium quality)                       │
+│    webp: +35         (optimized images)                     │
+│    mp4_low: +20      (mobile video)                         │
+│    mp4_high: +10     (HD video)                             │
+│    original: +5      (full quality)                         │
+│                                                             │
+│  Link Bonus:                                                │
+│    linkCountMultiplier × numLinks (max: maxLinkBonus)       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### Consumers
+
+| File | Usage |
+|------|-------|
+| `usePreloadOrchestrator.ts` | Queue, priorities, fields |
+| `useNeighborGraph.ts` | Graph traversal depth |
+| `extractPageLinks.ts` | Asset field names |
+| `imagePreDecode.ts` | Image fields |
+| `StorageManager.ts` | Size thresholds |
+| `DownloadManager.ts` | Queue settings |
+| `useStorageQuota.ts` | Storage limits |
+| `usePreloadProgress.ts` | Auto-cleanup |
+| `DownloadContext.tsx` | Queue settings |
+
+---
+
+## Environment Variables
+
+### Build-Time Variables
+
+| Variable | Used In | Purpose |
+|----------|---------|---------|
+| `NODE_ENV` | `next.config.mjs`, `config.ts` | Build/runtime mode |
+
+### Runtime Variables (NEXT_PUBLIC_*)
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `NEXT_PUBLIC_BACK_API` | - | Backend API URL |
+| `NEXT_PUBLIC_LOG_LEVEL` | `'info'` | Logger verbosity |
+
+### Usage in Code
+
+```typescript
+// API URL detection
+export const apiBaseURL = process.env.NEXT_PUBLIC_BACK_API || baseURLApi;
+axios.defaults.baseURL = apiBaseURL;
+
+// Logger level
+export const frontendLogLevel = process.env.NEXT_PUBLIC_LOG_LEVEL || 'info';
+
+// Development mode
+export const isDevelopment = process.env.NODE_ENV === 'development';
+export const isProduction = process.env.NODE_ENV === 'production';
+```
+
+Feature modules, hooks, components, and app initialization should import these
+exports from `frontend/src/config.ts` instead of reading `process.env` directly.
+
+---
+
+## Service Worker Configuration
+
+The service worker (`src/sw.ts`) uses `OFFLINE_CONFIG` for caching:
+
+```typescript
+import { OFFLINE_CONFIG } from './config/offline.config';
+
+// Cache strategies
+const serwist = new Serwist({
+  runtimeCaching: [
+    // Static assets - Cache First
+    {
+      matcher: ({ request }) => request.destination === 'image',
+      handler: new CacheFirst({
+        cacheName: OFFLINE_CONFIG.cacheNames.assets,
+      }),
+    },
+    // API requests - Network First
+    {
+      matcher: ({ url }) => url.pathname.startsWith('/api/'),
+      handler: new NetworkFirst({
+        cacheName: 'api-cache',
+        networkTimeoutSeconds: 10,
+      }),
+    },
+  ],
+});
+```
+
+#### Cacheable Extensions
+
+```typescript
+const CACHEABLE_EXTENSIONS = [
+  // Images
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico',
+  // Video
+  '.mp4', '.webm', '.mov',
+  // Audio
+  '.mp3', '.wav', '.ogg', '.m4a',
+  // Fonts
+  '.woff', '.woff2', '.ttf', '.eot',
+  // Code
+  '.css', '.js',
+];
+```
+
+---
+
+## Logger Configuration
+
+The logger (`src/lib/logger.ts`) provides structured logging:
+
+```typescript
+interface LoggerConfig {
+  level: LogLevel;          // 'debug' | 'info' | 'warn' | 'error'
+  isDevelopment: boolean;   // Colored vs JSON output
+  service: string;          // Service name for log aggregation
+}
+
+// Configuration from environment
+this.config = {
+  level: toLogLevel(frontendLogLevel),
+  isDevelopment,
+  service: 'tour-builder-frontend',
+};
+```
+
+#### Usage
+
+```typescript
+import { logger } from '@/lib/logger';
+
+logger.info('User logged in', { userId: '123' });
+logger.error('Failed to fetch', error);
+```
+
+---
+
+## Configuration Dependencies
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Configuration Flow                       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│              next.config.mjs (Build Config)                 │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ - Enables Serwist (PWA)                                 ││
+│  │ - Sets output mode (export/standalone)                  ││
+│  │ - Configures TypeScript/ESLint checking                 ││
+│  └─────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 config.ts (Runtime Config)                  │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ - API URLs (baseURLApi, apiBaseURL)                     ││
+│  │ - Runtime flags (isDevelopment, isProduction)           ││
+│  │ - Public log level                                      ││
+│  │ - App title, page titles                                ││
+│  │ - Storage keys                                          ││
+│  │ - External service keys (TinyMCE)                       ││
+│  └─────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+                              │
+               ┌──────────────┼──────────────┐
+               ▼              ▼              ▼
+┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
+│  offline.config.ts  │ │  preload.config.ts  │ │ menuAside/NavBar.ts │
+│  ┌────────────────┐ │ │  ┌────────────────┐ │ │ ┌────────────────┐  │
+│  │ Cache names    │ │ │  │ Queue settings │ │ │ │ Navigation     │  │
+│  │ Event names    │ │ │  │ Priorities     │ │ │ │ items          │  │
+│  │ Storage limits │ │ │  │ Asset fields   │ │ │ │ Permissions    │  │
+│  │ Retry config   │ │ │  │ Graph depth    │ │ │ │ Icons          │  │
+│  └────────────────┘ │ │  └────────────────┘ │ │ └────────────────┘  │
+└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
+          │                       │                       │
+          ▼                       ▼                       ▼
+┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
+│ Service Worker      │ │ Preload Hooks       │ │ Layout Components   │
+│ StorageManager      │ │ DownloadManager     │ │ AsideMenu           │
+│ DownloadEventBus    │ │ NeighborGraph       │ │ NavBar              │
+└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
+```
+
+---
+
+## Config Inventory
+
+| File | LOC | Purpose | Consumers |
+|------|-----|---------|-----------|
+| `next.config.mjs` | 44 | Build configuration | Next.js build |
+| `tailwind.config.js` | 114 | CSS theming | All components |
+| `postcss.config.js` | 8 | CSS processing | Build pipeline |
+| `prettier.config.js` | 12 | Code formatting | Development |
+| `tsconfig.json` | 30 | TypeScript compiler | Build, IDE |
+| `.eslintrc.cjs` | 50 | Linting rules | Build, IDE |
+| `config.ts` | 24 | Runtime settings and public env access | 30+ files |
+| `menuAside.ts` | 42 | Sidebar navigation | `AsideMenuLayer.tsx` |
+| `menuNavBar.ts` | 51 | Navbar navigation | `NavBar.tsx` |
+| `offline.config.ts` | 52 | PWA/offline settings | 9 files |
+| `preload.config.ts` | 94 | Preloading settings | 10 files |
+| **Total** | **517** | | |
+
+---
+
+## Best Practices
+
+### 1. Use Typed Constants
+
+```typescript
+// Good - const assertion for type safety
+export const OFFLINE_CONFIG = {
+  dbName: 'TourBuilderOffline',
+  // ...
+} as const;
+
+export type OfflineConfig = typeof OFFLINE_CONFIG;
+```
+
+### 2. Centralize Environment Access
+
+```typescript
+// Good - single source of truth
+// config.ts
+export const apiBaseURL = process.env.NEXT_PUBLIC_BACK_API || baseURLApi;
+
+// Consumer
+import { apiBaseURL } from '../config';
+```
+
+### 3. Group Related Settings
+
+```typescript
+// Good - logical grouping
+export const PRELOAD_CONFIG = {
+  queue: { maxConcurrent: 3, maxRetries: 3 },
+  priority: { currentPage: 1000, neighborBase: 500 },
+  storage: { warningPercent: 80, criticalPercent: 95 },
+};
+```
+
+### 4. Document Magic Numbers
+
+```typescript
+// Good - explain values
+storage: {
+  cacheApiMaxSize: 5 * 1024 * 1024,  // 5MB - files below go to Cache API
+  minFreeBuffer: 50 * 1024 * 1024,   // 50MB - minimum free space
+},
+```
+
+---
+
+## Related Documentation
+
+- [lib-module.md](./lib-module.md) - Offline storage using OFFLINE_CONFIG
+- [hooks-module.md](./hooks-module.md) - Preload hooks using PRELOAD_CONFIG
+- [layouts-module.md](./layouts-module.md) - Menu rendering
+- [stores-module.md](./stores-module.md) - styleSlice using storage keys
+
+---
+
+## Adding New Configuration
+
+### Step 1: Create Config File
+
+```typescript
+// src/config/feature.config.ts
+export const FEATURE_CONFIG = {
+  enabled: true,
+  settings: {
+    maxItems: 100,
+    timeout: 5000,
+  },
+} as const;
+
+export type FeatureConfig = typeof FEATURE_CONFIG;
+```
+
+### Step 2: Import Where Needed
+
+```typescript
+import { FEATURE_CONFIG } from '../config/feature.config';
+
+if (FEATURE_CONFIG.enabled) {
+  // Use settings
+}
+```
+
+### Step 3: Document in This File
+
+Add entry to Config Inventory table and explain usage.
diff --git a/frontend/docs/constructor-page-editor.md b/frontend/docs/constructor-page-editor.md
new file mode 100644
index 0000000..3a4f32e
--- /dev/null
+++ b/frontend/docs/constructor-page-editor.md
@@ -0,0 +1,1866 @@
+# Constructor Page Editor - E2E Documentation
+
+## Overview
+
+The Constructor is a full-featured visual editor for building interactive tour pages. It provides drag-and-drop element placement, background media configuration, transition setup, and real-time preview capabilities.
+
+**Main File:** `frontend/src/pages/constructor.tsx`
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Constructor Page                            │
+│  State Management │ Event Handlers │ Data Loading               │
+│  (constructor.tsx - orchestration layer)                        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│              Constructor-Specific Hooks                          │
+│  useConstructorElements │ useConstructorPageActions             │
+│  useCanvasElapsedTime │ useCanvasElementDrag │ useTransitionPreview │
+│  useMediaDurationProbe │ useIconPreload                          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│              Constructor Components                              │
+│  ConstructorToolbar │ CanvasBackground │ CanvasElement           │
+│  ElementEditorPanel │ PageSelector │ InteractionModeToggle      │
+│  TransitionPreviewOverlay │ AssetSelectCompact │ etc.           │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│              UI Element Components (3 files)                     │
+│  GalleryCarouselOverlay │ UiElementRenderer │ ElementPreview    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                    Shared Runtime Hooks                          │
+│  usePreloadOrchestrator │ usePageSwitch │ useTransitionPlayback │
+│  useBackgroundTransition │ useDraggable │ useOutsideClick       │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                    Helper Libraries                              │
+│  elementDefaults │ elementStyles │ elementEffects               │
+│  constructorHelpers │ navigationHelpers │ mediaHelpers          │
+│  assetUrl │ parseJson │ extractPageLinks                        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                       Data Layer                                 │
+│  Tour Pages API │ Assets API │ Project Element Defaults │ S3    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Interaction Modes
+
+### Edit Mode
+
+- Click element → Select for property editing
+- Drag element → Reposition on canvas
+- Global action buttons (fullscreen, sound, offline) render as system controls.
+  They can be selected, dragged, hidden, disabled, styled, and assigned custom
+  icons, but cannot be deleted. Hidden controls still render as ghost controls in
+  edit mode.
+- Properties panel shows selected element
+- Menu shows element creation options
+- Info Panel and image detail overlays are non-blocking previews in edit mode:
+  they render from the selected element only, do not use runtime open state, and
+  pass canvas clicks through except for their small drag handles.
+
+### Interact Mode
+
+- Click navigation → Preview navigation/transition
+- Global action buttons use runtime rendering with canvas-relative positioning
+  and dimensions. In edit mode all system controls remain visible/selectable,
+  hidden controls render as ghost controls, and actions are blocked so buttons
+  can be dragged without toggling fullscreen, sound, or offline mode.
+- Disabled navigation and Info Panel elements keep hover/focus/active visuals, but their actions, click audio, and click-persisted hover state are ignored
+- Info Panel elements can set `infoPanelOpenByDefault: true` from the General tab; constructor interact mode opens every enabled matching panel when the page renders, while edit mode continues to show only the selected-element preview. Detail panel and fullscreen gallery state are scoped to the originating Info Panel ID.
+- Cannot drag or select elements
+- Used for testing page flow
+- Tests navigation elements and video transitions
+- Element hover/click audio effects are active. The constructor uses the same
+  global sound state as runtime and renders global action buttons through
+  `RuntimeControls`. Current unsaved element/background audio changes are
+  included so the sound button appears immediately while editing.
+- Runtime chrome is hidden while fullscreen gallery overlays are open. In edit
+  mode, system controls continue to render so they can be selected and edited.
+
+---
+
+## Data Models
+
+### CanvasElement
+
+```typescript
+interface CanvasElement extends ElementStyleProperties, ElementEffectProperties {
+  id: string;
+  type: CanvasElementType;
+  label: string;
+
+  // Percentage-based positioning (0-100)
+  xPercent: number;
+  yPercent: number;
+
+  // Common properties
+  iconUrl?: string;
+  mediaUrl?: string;
+
+  // Animation timing
+  appearDelaySec: number;
+  appearDurationSec: number | null;
+
+  // Navigation (for navigation elements)
+  navLabel?: string;
+  navType?: 'forward' | 'back';
+  navDisabled?: boolean;
+  targetPageSlug?: string;  // Slug-based navigation (consistent across environments)
+  targetPageId?: string;    // @deprecated - use targetPageSlug
+  transitionVideoUrl?: string;
+  transitionReverseMode?: 'auto_reverse' | 'separate_video';
+  reverseVideoUrl?: string;
+  transitionDurationSec?: number;
+
+  // Tooltip
+  tooltipTitle?: string;
+  tooltipText?: string;
+  tooltipTitleFontFamily?: string;
+  tooltipTextFontFamily?: string;
+
+  // Description
+  descriptionTitle?: string;
+  descriptionText?: string;
+  descriptionTitleFontSize?: string;
+  descriptionTextFontSize?: string;
+  descriptionTitleFontFamily?: string;
+  descriptionTextFontFamily?: string;
+  descriptionTitleColor?: string;
+  descriptionTextColor?: string;
+  descriptionBackgroundColor?: string;
+
+  // Gallery
+  galleryCards?: GalleryCard[];
+  galleryHeaderImageUrl?: string;
+  galleryTitle?: string;
+  galleryInfoSpans?: GalleryInfoSpan[];
+  galleryColumns?: number;
+  galleryTitleFontFamily?: string;
+  galleryCardFontFamily?: string;
+
+  // Gallery Carousel overlay settings
+  galleryCarouselPrevIconUrl?: string;
+  galleryCarouselNextIconUrl?: string;
+  galleryCarouselBackIconUrl?: string;
+  galleryCarouselBackLabel?: string;
+  galleryCarouselPrevX?: number;
+  galleryCarouselPrevY?: number;
+  galleryCarouselNextX?: number;
+  galleryCarouselNextY?: number;
+  galleryCarouselBackX?: number;
+  galleryCarouselBackY?: number;
+  galleryCarouselPrevWidth?: string;
+  galleryCarouselPrevHeight?: string;
+  galleryCarouselNextWidth?: string;
+  galleryCarouselNextHeight?: string;
+  galleryCarouselBackWidth?: string;
+  galleryCarouselBackHeight?: string;
+
+  // Carousel
+  carouselSlides?: CarouselSlide[];
+  carouselPrevIconUrl?: string;
+  carouselNextIconUrl?: string;
+  carouselCaptionFontFamily?: string;
+
+  // Media players
+  mediaAutoplay?: boolean;
+  mediaLoop?: boolean;
+  mediaMuted?: boolean;
+}
+
+// Styling properties (from ElementStyleProperties)
+interface ElementStyleProperties {
+  width?: string;
+  height?: string;
+  minWidth?: string;
+  maxWidth?: string;
+  minHeight?: string;
+  maxHeight?: string;
+  fontSize?: string;
+  lineHeight?: string;
+  fontWeight?: string;
+  fontFamily?: string;
+  color?: string;
+  backgroundColor?: string;
+  border?: string;
+  borderRadius?: string;
+  opacity?: number;
+  boxShadow?: string;
+  padding?: string;
+  margin?: string;
+  gap?: string;
+  display?: string;
+  position?: string;
+  justifyContent?: string;
+  alignItems?: string;
+  textAlign?: string;
+  zIndex?: number;
+}
+
+// Effect properties (from ElementEffectProperties)
+interface ElementEffectProperties {
+  appearAnimation?: AppearAnimationType;
+  appearAnimationDuration?: string;
+  appearAnimationEasing?: string;
+  hoverScale?: string;
+  hoverOpacity?: string;
+  hoverBackgroundColor?: string;
+  hoverColor?: string;
+  hoverBoxShadow?: string;
+  hoverTransitionDuration?: string;
+  focusScale?: string;
+  focusOpacity?: string;
+  focusOutline?: string;
+  focusBoxShadow?: string;
+  activeScale?: string;
+  activeOpacity?: string;
+  activeBackgroundColor?: string;
+}
+
+type AppearAnimationType = '' | 'fade' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'scale';
+```
+
+### Supporting Types
+
+```typescript
+// Gallery card item
+interface GalleryCard {
+  id: string;
+  imageUrl: string;
+  title: string;
+  description: string;
+}
+
+// Gallery info span (brief note badge displayed in header)
+interface GalleryInfoSpan {
+  id: string;
+  text: string;
+}
+
+// Carousel slide item
+interface CarouselSlide {
+  id: string;
+  imageUrl: string;
+  caption: string;
+}
+```
+
+### Element Types
+
+| Type | Description |
+|------|-------------|
+| `navigation_next` | Forward navigation button |
+| `navigation_prev` | Backward navigation button |
+| `spot` | Hotspot/clickable area |
+| `description` | Title + text block |
+| `tooltip` | Icon with hover text overlay |
+| `gallery` | Multi-card image gallery |
+| `carousel` | Image carousel with navigation |
+| `logo` | Logo element |
+| `video_player` | Embedded video with controls |
+| `audio_player` | Embedded audio with controls |
+| `popup` | Popup/modal dialog |
+| `info_panel` | Interactive info panel with sections, images, and 360 embeds |
+
+**Note:** Element types are stored as TEXT (not ENUM) in the database, allowing new types to be added without migrations. There are 12 predefined element types. Default settings for each type are sourced from `project_element_defaults` (project-specific) which are automatically snapshotted from `element_type_defaults` (global) when a project is created. The constructor fetches project-specific defaults via `/api/project-element-defaults?projectId=xxx`.
+
+### Page Schema
+
+```typescript
+interface ConstructorSchema {
+  elements?: CanvasElement[];
+}
+
+// Stored in tour_page.ui_schema_json as JSON string
+```
+
+---
+
+## UI Components
+
+### Canvas
+
+The main editing area where elements are placed and manipulated.
+
+```tsx
+<div
+  ref={canvasRef}
+  className="relative w-full h-full overflow-hidden"
+  style={{
+    backgroundImage: backgroundImageUrl ? `url(${backgroundImageUrl})` : undefined,
+    backgroundSize: 'cover',
+    backgroundPosition: 'center',
+  }}
+>
+  {/* Background Video */}
+  {backgroundVideoUrl && (
+    <video autoPlay loop muted playsInline className="absolute inset-0 object-cover" />
+  )}
+
+  {/* Canvas Elements */}
+  {elements.filter(isElementVisibleOnCanvas).map((element) => (
+    <CanvasElementComponent
+      key={element.id}
+      element={element}
+      isSelected={selectedElementId === element.id}
+      onSelect={() => selectElement(element.id)}
+      onDragStart={handleDragStart}
+    />
+  ))}
+</div>
+```
+
+### Controls Panel (Top-Left, Draggable)
+
+```
+┌─────────────────────────────────┐
+│  Page: [Dropdown ▼]             │
+│  Mode: [Edit] [Interact]        │
+│  [Exit to Assets]               │
+└─────────────────────────────────┘
+```
+
+**Features:**
+- Page selector dropdown
+- Edit/Interact mode toggle
+- Exit button to return to assets
+
+### Constructor Menu (Right Side, Collapsible)
+
+```
+┌─────────────────────────────────┐
+│  CONSTRUCTOR MENU          [×]  │
+├─────────────────────────────────┤
+│  Background Image         [▼]   │
+│  Background Video         [▼]   │
+│  Background Audio         [▼]   │
+├─────────────────────────────────┤
+│  [+ Navigation: Forward]        │
+│  [+ Navigation: Back]           │
+│  [+ Hotspot]                    │
+│  [+ Description]                │
+│  [+ Tooltip]                    │
+│  [+ Gallery]                    │
+│  [+ Carousel]                   │
+│  [+ Logo]                       │
+│  [+ Video Player]               │
+│  [+ Audio Player]               │
+│  [+ Popup]                      │
+├─────────────────────────────────┤
+│  [Create New Page]              │
+│  [Save]                         │
+│  [Save to Stage]                │
+│  [Exit]                         │
+└─────────────────────────────────┘
+```
+
+**Note:** The constructor always edits the **dev** environment. Changes are saved to dev pages automatically. Use "Save to Stage" to promote dev content to the stage environment for preview/review before publishing to production.
+
+### Element Editor (Right Side, Collapsible, Tabbed)
+
+Displays context-sensitive properties based on selected element type. The editor uses a **tabbed interface** (via `ElementEditorPanel` component):
+
+```
+┌───────────────────────────────────────┐
+│  ELEMENT EDITOR                  [×]  │
+├───────────────────────────────────────┤
+│  [General] [CSS Styles] [Effects]     │
+├───────────────────────────────────────┤
+│  Tab content based on selection       │
+└───────────────────────────────────────┘
+```
+
+**Tab State:**
+```typescript
+const [elementEditorTab, setElementEditorTab] = useState<'general' | 'css' | 'effects'>('general');
+```
+
+**General Tab** - Element-specific settings:
+- Common: Label, Appear delay (sec), Appear duration (sec)
+- Navigation: Direction, Disabled, Icon, Target page, Transition video, Reverse mode
+- Tooltip: Icon, Title, Text, Title/Text font families
+- Description: Icon, Title, Text, Typography (font sizes, families, colors, background)
+- Gallery: Header image, Title, Info spans (badges), Columns, Cards array (image, title, description), Title/Card font families, Carousel button icons/positions/dimensions
+- Carousel: Slides array (image, caption), Prev/Next icon URLs, Caption font family
+- Media: URL, Autoplay, Loop, Muted
+
+**Effects Tab** - Uses effect settings from `lib/elementEffects.ts`:
+- Appear Animation: Type (fade, slide-up/down/left/right, scale), Duration, Easing
+- Hover Effects: Scale, Opacity (%), Background color, Text color, Box shadow, Transition duration
+- Focus Effects: Scale, Opacity (%), Outline, Box shadow
+- Active/Press Effects: Scale, Opacity (%), Background color
+
+**CSS Styles Tab** - Uses `StyleSettingsSectionCompact` component:
+- Dimensions: Width, Height, Min/Max Width, Min/Max Height
+- Spacing: Margin, Padding, Gap
+- Typography: Font size, Line height, Font weight, Font family
+- Colors: Color, Background color
+- Borders: Border, Border radius
+- Effects: Opacity (%), Box shadow
+- Layout: Display, Position, Justify content, Align items, Text align, Z-index
+
+Opacity editors display clamped percentages from `0` to `100`; the constructor
+converts those values back to CSS opacity strings from `0` to `1` before saving
+elements in `tour_pages.ui_schema_json`.
+
+---
+
+## Element Positioning
+
+### Percentage-Based System
+
+Elements use percentage-based positioning for responsive layouts:
+
+```typescript
+// Element position stored as percentages
+element.xPercent = 50;  // 50% from left
+element.yPercent = 30;  // 30% from top
+
+// Rendered with CSS
+style={{
+  left: `${element.xPercent}%`,
+  top: `${element.yPercent}%`,
+  transform: 'translate(-50%, -50%)',  // Center on point
+}}
+```
+
+### Drag and Drop
+
+```typescript
+// Start drag
+const onElementMouseDown = (event: MouseEvent, elementId: string) => {
+  if (mode !== 'edit') return;
+
+  const element = elements.find(e => e.id === elementId);
+  const canvas = canvasRef.current;
+  const rect = canvas.getBoundingClientRect();
+
+  // Calculate offset from element center
+  const elementX = (element.xPercent / 100) * rect.width;
+  const elementY = (element.yPercent / 100) * rect.height;
+  const offsetX = event.clientX - rect.left - elementX;
+  const offsetY = event.clientY - rect.top - elementY;
+
+  dragStateRef.current = { elementId, offsetX, offsetY };
+};
+
+// During drag
+const onPointerMove = (event: PointerEvent) => {
+  if (!dragStateRef.current) return;
+
+  const canvas = canvasRef.current;
+  const rect = canvas.getBoundingClientRect();
+
+  // Calculate new percentage position
+  const x = event.clientX - rect.left - dragStateRef.current.offsetX;
+  const y = event.clientY - rect.top - dragStateRef.current.offsetY;
+
+  const xPercent = Math.max(0, Math.min(100, (x / rect.width) * 100));
+  const yPercent = Math.max(0, Math.min(100, (y / rect.height) * 100));
+
+  updateElement(dragStateRef.current.elementId, { xPercent, yPercent });
+};
+
+// End drag
+const onPointerUp = () => {
+  dragStateRef.current = null;
+};
+```
+
+---
+
+## Element Styling
+
+### Style Builder Function
+
+```typescript
+const buildCanvasElementStyle = (element: CanvasElement): CSSProperties => {
+  const style: CSSProperties = {};
+
+  // Dimensions
+  if (element.width) style.width = element.width;
+  if (element.height) style.height = element.height;
+  if (element.minWidth) style.minWidth = element.minWidth;
+  if (element.maxWidth) style.maxWidth = element.maxWidth;
+  if (element.minHeight) style.minHeight = element.minHeight;
+  if (element.maxHeight) style.maxHeight = element.maxHeight;
+
+  // Spacing
+  if (element.margin) style.margin = element.margin;
+  if (element.padding) style.padding = element.padding;
+  if (element.gap) style.gap = element.gap;
+
+  // Typography
+  if (element.fontSize) style.fontSize = element.fontSize;
+  if (element.lineHeight) style.lineHeight = element.lineHeight;
+  if (element.fontWeight) style.fontWeight = element.fontWeight;
+  if (element.fontFamily) style.fontFamily = element.fontFamily;
+  if (element.color) style.color = element.color;
+
+  // Appearance
+  if (element.backgroundColor) style.backgroundColor = element.backgroundColor;
+  if (element.border) style.border = element.border;
+  if (element.borderRadius) style.borderRadius = element.borderRadius;
+  if (element.opacity !== undefined) style.opacity = element.opacity;
+  if (element.boxShadow) style.boxShadow = element.boxShadow;
+
+  // Layout
+  if (element.display) style.display = element.display;
+  if (element.position) style.position = element.position;
+  if (element.justifyContent) style.justifyContent = element.justifyContent;
+  if (element.alignItems) style.alignItems = element.alignItems;
+  if (element.textAlign) style.textAlign = element.textAlign;
+  if (element.zIndex !== undefined) style.zIndex = element.zIndex;
+
+  return style;
+};
+```
+
+`zIndex` is also applied to the outer absolutely-positioned element wrapper in
+both constructor and runtime rendering. This is required for sibling elements to
+stack according to the CSS panel value instead of only by array/render order.
+
+---
+
+## Animation Timing
+
+### Element Visibility
+
+Elements can appear and disappear based on timing:
+
+```typescript
+interface CanvasElement {
+  appearDelaySec: number;           // Seconds before element appears
+  appearDurationSec: number | null; // Duration visible (null = forever)
+}
+
+const isElementVisibleOnCanvas = (element: CanvasElement): boolean => {
+  const delay = element.appearDelaySec || 0;
+
+  // Not yet visible
+  if (canvasElapsedSec < delay) return false;
+
+  // Always visible (no duration limit)
+  if (element.appearDurationSec === null) return true;
+
+  // Check if within visibility window
+  const endTime = delay + element.appearDurationSec;
+  return canvasElapsedSec <= endTime;
+};
+```
+
+### Canvas Timer
+
+```typescript
+// Track elapsed time for animation
+const [canvasElapsedSec, setCanvasElapsedSec] = useState(0);
+
+useEffect(() => {
+  const interval = setInterval(() => {
+    setCanvasElapsedSec((prev) => prev + 0.1);
+  }, 100);
+
+  return () => clearInterval(interval);
+}, []);
+
+// Reset on page change
+useEffect(() => {
+  setCanvasElapsedSec(0);
+}, [activePageId]);
+```
+
+**Performance Note:** The 100ms timer causes component re-renders every 100ms. This is intentional for element visibility animations but requires careful handling of image components (see Image Rendering Strategy below).
+
+---
+
+## Background Media
+
+### Image Rendering Strategy
+
+The constructor uses a conditional rendering approach for images to prevent performance issues:
+
+```typescript
+// For blob URLs: use native <img> (no re-fetch on re-render)
+// For regular URLs: use Next.js Image (optimization benefits)
+{url.startsWith('blob:') ? (
+  <img src={url} className="..." />
+) : (
+  <NextImage src={url} fill unoptimized />
+)}
+```
+
+**Why this matters:**
+- Next.js Image component re-fetches the `src` on every render, even with `unoptimized` prop
+- The 100ms canvas timer causes ~10 re-renders per second
+- For blob URLs this would cause thousands of unnecessary fetch requests
+- Native `<img>` tags are cached by the browser and don't re-fetch
+
+**Applied to:**
+- Background images (blob URLs from preload cache)
+- Element icons (tooltip, description, gallery, carousel)
+- Any dynamically resolved asset URL that may be a blob
+
+| URL Type | Component | Reason |
+|----------|-----------|--------|
+| `blob:...` | Native `<img>` | No re-fetch, already in memory |
+| `https://...` | `<NextImage unoptimized>` | Optimization benefits, less frequent re-renders |
+| Presigned S3 | `<NextImage unoptimized>` | Falls back gracefully |
+
+### Background Image
+
+```typescript
+// Stored in tour_page
+background_image_url: string;
+
+// Applied to canvas
+style={{
+  backgroundImage: `url(${backgroundImageUrl})`,
+  backgroundSize: 'cover',
+  backgroundPosition: 'center',
+}}
+```
+
+### Background Video
+
+Background videos support configurable playback settings for precise control over autoplay, looping, and time boundaries.
+
+```typescript
+// Stored in tour_page
+background_video_url: string;
+background_video_autoplay: boolean;      // Default: true
+background_video_loop: boolean;          // Default: true
+background_video_muted: boolean;         // Default: true
+background_video_start_time: number | null;  // Start time in seconds (0.1s precision)
+background_video_end_time: number | null;    // End time in seconds (0.1s precision)
+
+// Rendered using useBackgroundVideoPlayback hook
+const { videoRef } = useBackgroundVideoPlayback({
+  videoUrl: backgroundVideoUrl,
+  autoplay: backgroundVideoAutoplay,
+  loop: backgroundVideoLoop,
+  muted: backgroundVideoMuted,
+  startTime: backgroundVideoStartTime,
+  endTime: backgroundVideoEndTime,
+});
+
+<video
+  ref={videoRef}
+  src={backgroundVideoUrl}
+  autoPlay={backgroundVideoAutoplay}
+  loop={backgroundVideoEndTime == null ? backgroundVideoLoop : false}
+  muted={backgroundVideoMuted}
+  playsInline
+  className="absolute inset-0 w-full h-full object-cover -z-10"
+/>
+```
+
+**Playback Settings (configured in BackgroundSettingsEditor):**
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| Autoplay | boolean | true | Start video playback automatically |
+| Loop | boolean | true | Loop video continuously |
+| Sound | boolean | false (muted) | Enable audio (toggled as "Sound" in UI) |
+| Start (sec) | number | null | Start playback at this time |
+| End (sec) | number | null | Stop/loop at this time |
+
+**Note:** When `end_time` is set, native HTML5 `loop` is disabled and looping is handled via JavaScript to properly seek back to `start_time`.
+
+### Background 360/Embed
+
+```typescript
+// Stored in tour_page
+background_embed_url: string;
+
+// Rendered by CanvasBackground as a full-canvas iframe layer
+<iframe
+  src={backgroundEmbedUrl}
+  className="absolute inset-0 h-full w-full border-0"
+/>
+```
+
+The constructor background dropdown includes **Background 360**, sourced from `asset_type='embed'` assets. Selecting a 360/embed background clears image and video background URLs; background audio remains independent.
+
+Constructor asset selectors load the full project asset list through
+`useConstructorData()` and then filter options client-side by `asset_type` and
+`type` for image, background image, video, audio, transition, icon, and embed
+dropdowns. There is no frontend `limit` applied to the project asset query.
+
+### Background Audio
+
+```typescript
+// Stored in tour_page
+background_audio_url: string;
+
+// Rendered as hidden audio
+<audio
+  src={backgroundAudioUrl}
+  autoPlay
+  loop
+  className="hidden"
+/>
+```
+
+---
+
+## Transition Configuration
+
+### Transition Properties
+
+```typescript
+// On navigation elements
+transitionVideoUrl: string;           // Forward transition video
+transitionReverseMode: 'auto_reverse' | 'separate_video';
+reverseVideoUrl: string;              // Separate back transition video
+transitionDurationSec: number;        // Auto-detected from video
+```
+
+### Reverse Modes
+
+| Mode | Description |
+|------|-------------|
+| `auto_reverse` | Play forward video in reverse for back navigation |
+| `separate_video` | Use separate video for back navigation |
+
+### Transition Preview
+
+```typescript
+interface TransitionPreviewState {
+  videoUrl: string;
+  storageKey: string;        // Raw storage path for cache lookup (enables presigned URL independence)
+  reverseVideoUrl?: string;
+  reverseStorageKey?: string;
+  reverseMode: 'none' | 'reverse' | 'separate';
+  durationSec?: number;
+  title: string;
+}
+
+// Preview workflow
+const previewTransition = async (element: CanvasElement, direction: 'forward' | 'back') => {
+  // 1. Set preview state with storage key for cache lookup
+  setTransitionPreview({
+    videoUrl: element.transitionVideoUrl,
+    storageKey: element.transitionVideoUrl,  // Raw path for instant blob URL lookup
+    reverseMode: direction === 'forward' ? 'none' :
+      element.transitionReverseMode === 'separate_video' ? 'separate' : 'reverse',
+    reverseVideoUrl: element.reverseVideoUrl,
+    reverseStorageKey: element.reverseVideoUrl,
+    durationSec: element.transitionDurationSec,
+    title: `${element.navLabel || element.label} · ${direction}`,
+  });
+
+  // 2. useTransitionPlayback resolves video source:
+  //    a) Try getReadyBlobUrl(storageKey) - instant O(1) Map lookup
+  //    b) Try getCachedBlobUrl(storageKey) - Cache API lookup (~5ms)
+  //    c) Fallback to network fetch with presigned URL
+  // 3. Video loads and plays (forward or reverse)
+  // 4. On complete: switch to target page via usePageSwitch
+  // 5. Clear preview state
+};
+```
+
+### Gallery Carousel Overlay
+
+When a user clicks on a gallery card in interact mode, a fullscreen carousel overlay opens showing the card images. The overlay uses `GalleryCarouselOverlay` component with customizable navigation buttons.
+
+```typescript
+// Gallery element carousel settings (stored in element)
+interface GalleryCarouselSettings {
+  galleryCarouselPrevIconUrl?: string;   // Previous button icon
+  galleryCarouselNextIconUrl?: string;   // Next button icon
+  galleryCarouselBackIconUrl?: string;   // Back/close button icon
+  galleryCarouselBackLabel?: string;     // Back button label (default: 'BACK')
+  // Button positions (percentage-based)
+  galleryCarouselPrevX?: number;
+  galleryCarouselPrevY?: number;
+  galleryCarouselNextX?: number;
+  galleryCarouselNextY?: number;
+  galleryCarouselBackX?: number;
+  galleryCarouselBackY?: number;
+  // Button dimensions (CSS values)
+  galleryCarouselPrevWidth?: string;
+  galleryCarouselPrevHeight?: string;
+  galleryCarouselNextWidth?: string;
+  galleryCarouselNextHeight?: string;
+  galleryCarouselBackWidth?: string;
+  galleryCarouselBackHeight?: string;
+}
+
+// Constructor edit mode: buttons are draggable for positioning
+{activeGalleryCarousel && (
+  <GalleryCarouselOverlay
+    cards={activeGalleryCarousel.element.galleryCards || []}
+    initialIndex={activeGalleryCarousel.initialIndex}
+    onClose={() => setActiveGalleryCarousel(null)}
+    resolveUrl={resolveUrlWithBlob}
+    prevIconUrl={element.galleryCarouselPrevIconUrl}
+    nextIconUrl={element.galleryCarouselNextIconUrl}
+    backIconUrl={element.galleryCarouselBackIconUrl}
+    backLabel={element.galleryCarouselBackLabel || 'BACK'}
+    prevX={element.galleryCarouselPrevX}
+    prevY={element.galleryCarouselPrevY}
+    // ... other position/dimension props
+    isEditMode={isConstructorEditMode}
+    onButtonPositionChange={handleCarouselButtonPositionChange}
+  />
+)}
+```
+
+**Features:**
+- Fullscreen overlay with centered card image
+- Previous/Next navigation with customizable icons
+- Back button to close overlay
+- In constructor edit mode: drag buttons to reposition them
+- Button positions saved as percentage coordinates in element settings
+
+---
+
+## Asset Selection
+
+### Asset Filtering
+
+```typescript
+// Image assets for backgrounds
+const backgroundImageOptions = assets.filter(
+  (a) => a.asset_type === 'image' && isBackgroundImageAsset(a)
+);
+
+// Video assets for backgrounds and players
+const videoAssetOptions = assets.filter(
+  (a) => a.asset_type === 'video'
+);
+
+// Transition videos (tagged in asset name or type)
+const transitionVideoOptions = assets.filter(
+  (a) => a.asset_type === 'video' && /\[TRANSITION\]/i.test(a.name)
+);
+
+// Icon assets for buttons and tooltips
+const iconAssetOptions = assets.filter(
+  (a) => a.asset_type === 'image' && isIconAsset(a)
+);
+```
+
+### Asset Selector Component
+
+```tsx
+<select
+  value={selectedAssetUrl}
+  onChange={(e) => updateElement({ iconUrl: e.target.value })}
+>
+  <option value="">Select asset...</option>
+  {iconAssetOptions.map((asset) => (
+    <option key={asset.id} value={asset.cdn_url}>
+      {asset.name}
+    </option>
+  ))}
+  {/* Fallback for custom URLs */}
+  {selectedAssetUrl && !iconAssetOptions.find(a => a.cdn_url === selectedAssetUrl) && (
+    <option value={selectedAssetUrl}>
+      {selectedAssetUrl} (custom)
+    </option>
+  )}
+</select>
+```
+
+---
+
+## Duration Detection
+
+### Media Duration Probing
+
+```typescript
+const probeMediaDuration = async (url: string): Promise<number | null> => {
+  return new Promise((resolve) => {
+    const media = document.createElement('video');
+    media.preload = 'metadata';
+
+    const timeout = setTimeout(() => {
+      media.remove();
+      resolve(null);
+    }, 12000);
+
+    media.onloadedmetadata = () => {
+      clearTimeout(timeout);
+      const duration = media.duration;
+      media.remove();
+
+      if (isFinite(duration) && duration > 0) {
+        resolve(duration);
+      } else {
+        resolve(null);
+      }
+    };
+
+    media.onerror = () => {
+      clearTimeout(timeout);
+      media.remove();
+      resolve(null);
+    };
+
+    media.src = url;
+  });
+};
+```
+
+### Auto-Populate Duration
+
+```typescript
+// When transition video selected
+const handleTransitionVideoChange = async (videoUrl: string) => {
+  updateElement({ transitionVideoUrl: videoUrl });
+
+  // Auto-detect duration
+  const duration = await probeMediaDuration(videoUrl);
+  if (duration) {
+    updateElement({ transitionDurationSec: duration });
+  }
+};
+```
+
+If a page save includes an auto-reverse transition video that fails the backend
+guardrails, the save request fails with an explicit validation message. The
+guardrails currently cover both very large source files (`16 GiB+`) and videos
+whose stored resolution and duration imply too much decoded frame data for the
+current VM. The constructor surfaces that message in its top-left error banner,
+so the editor sees immediately why the page was not saved.
+
+---
+
+## Preload Integration
+
+### usePreloadOrchestrator
+
+The preload orchestrator handles asset caching and provides instant blob URLs for smooth transitions.
+
+```typescript
+const preloadOrchestrator = usePreloadOrchestrator({
+  pages: pages.map((p) => ({
+    id: p.id,
+    background_image_url: p.background_image_url,
+    background_video_url: p.background_video_url,
+    background_audio_url: p.background_audio_url,
+  })),
+  pageLinks,                        // Navigation connections from extractPageLinksAndElements
+  elements: allPagesPreloadElements, // Asset URLs from extractPageLinksAndElements
+  currentPageId: activePageId,
+  enabled: !isLoading && !!activePageId,
+  // maxNeighborDepth defaults to 1 - only preload immediate neighbors
+});
+
+// Page switch hook for smooth background transitions (uses blob URLs from preload cache)
+const pageSwitch = usePageSwitch({
+  preloadCache: preloadOrchestrator
+    ? {
+        getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,
+        getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+        preloadedUrls: preloadOrchestrator.preloadedUrls,
+      }
+    : undefined,
+});
+```
+
+### Blob URL System
+
+Assets are downloaded directly from S3, cached in the browser's Cache API, and served as blob URLs for instant display. The system uses **storage key mapping** to enable reliable cache lookups regardless of which presigned URL was used for download.
+
+```typescript
+// Lookup by storage key (canonical path - most reliable)
+const readyUrl = preloadOrchestrator.getReadyBlobUrl(storagePath);
+
+// Lookup by resolved URL (fallback)
+const readyUrl = preloadOrchestrator.getReadyBlobUrl(resolvedUrl);
+
+// Fallback: get cached blob URL from Cache API
+const cachedUrl = await preloadOrchestrator.getCachedBlobUrl(storagePath);
+
+// Check if URL is preloaded
+const isReady = preloadOrchestrator.preloadedUrls.has(storagePath);
+```
+
+**Preload Flow:**
+1. Collect storage paths from current page + neighbors (depth=1)
+2. Batch fetch presigned URLs from backend (`POST /api/file/presign`)
+3. Download asset directly from S3 (or via proxy if CORS not configured)
+4. Store in browser Cache API under download URL
+5. **Store in Cache API under storage key** (enables post-refresh lookups)
+6. Create blob URL from cache
+7. Pre-decode images for instant paint
+8. **Map both download URL and storage key to blob URL in readyBlobUrlsRef**
+
+**Storage Key Mapping (Key Feature):**
+
+The storage key is the canonical identifier (e.g., `assets/project-123/video.mp4`) that remains constant, while presigned URLs change with each request (different signatures). By mapping storage keys to blob URLs:
+
+| Scenario | Download URL | Storage Key | Lookup Result |
+|----------|-------------|-------------|---------------|
+| Same session | `https://s3...?Sig=ABC` | `assets/vid.mp4` | ✅ Instant via storage key |
+| New presigned URL | `https://s3...?Sig=XYZ` | `assets/vid.mp4` | ✅ Instant via storage key |
+| Page refresh | N/A (cache cleared) | `assets/vid.mp4` | ✅ From Cache API |
+
+### usePageSwitch Integration
+
+The constructor uses `usePageSwitch` for smooth page transitions without black flashes:
+
+```typescript
+// Helper to switch pages without flash
+const switchToPage = useCallback(async (page: TourPage | null) => {
+  // Update storage path state for editing/saving purposes
+  setBackgroundImageUrl(page?.background_image_url || '');
+  setBackgroundVideoUrl(page?.background_video_url || '');
+  setBackgroundAudioUrl(page?.background_audio_url || '');
+
+  // Use hook to resolve and set blob URLs for display
+  await pageSwitch.switchToPage(
+    page
+      ? {
+          id: page.id,
+          background_image_url: page.background_image_url,
+          background_video_url: page.background_video_url,
+          background_audio_url: page.background_audio_url,
+        }
+      : null,
+  );
+}, [pageSwitch]);
+
+// Canvas background uses resolved blob URLs
+// User's selection (backgroundImageUrl) takes priority over pageSwitch state
+// This ensures manual changes via dropdown are immediately reflected
+const backgroundImageSrc = backgroundImageUrl
+  ? resolveUrlWithBlob(backgroundImageUrl)  // Resolves via blob cache or direct URL
+  : pageSwitch.currentBgImageUrl;           // Fallback during transitions
+```
+
+The `resolveUrlWithBlob` callback depends on `preloadOrchestrator.readyUrlsVersion` to re-render when blob URLs become ready after preload.
+
+The hook provides:
+- **previousBgImageUrl** - Previous background for overlay during transition
+- **currentBgImageUrl** - Resolved blob URL (or presigned URL) for current page
+- **isSwitching** - Whether a page switch is in progress
+- **isNewBgReady** - Whether the new background has been decoded and is ready to paint
+- **markBackgroundReady()** - Call when background image loads
+- **clearPreviousBackground()** - Remove the overlay after new background is ready
+
+### Extracting Page Links and Elements
+
+Navigation elements and preload assets are extracted from `ui_schema_json` using the shared utility:
+
+```typescript
+import { extractPageLinksAndElements } from '../lib/extractPageLinks';
+
+// In loadData():
+const { pageLinks, preloadElements } = extractPageLinksAndElements(pageRows);
+
+setPageLinks(pageLinks);              // For neighbor graph (navigation connections)
+setAllPagesPreloadElements(preloadElements);  // For preload queue (asset URLs)
+```
+
+The utility extracts:
+1. **pageLinks** - Navigation connections (`from_pageId → to_pageId`) for the neighbor graph
+2. **preloadElements** - Element asset URLs (icons, media, transitions) for preloading
+
+This enables preloading of connected pages and their assets based on navigation structure.
+
+### useTransitionPlayback Integration
+
+The constructor uses `useTransitionPlayback` for video transition playback with preload cache integration:
+
+```typescript
+const { isBuffering: isReverseBuffering } = useTransitionPlayback({
+  videoRef: transitionVideoRef,
+  transition: transitionPreview
+    ? {
+        videoUrl: resolveAssetPlaybackUrl(transitionPreview.videoUrl),
+        storageKey: transitionPreview.storageKey,  // Raw path for cache lookup
+        reverseMode: transitionPreview.reverseMode,
+        reverseVideoUrl: transitionPreview.reverseVideoUrl
+          ? resolveAssetPlaybackUrl(transitionPreview.reverseVideoUrl)
+          : undefined,
+        durationSec: transitionPreview.durationSec,
+        targetPageId: pendingNavigationPageId || undefined,
+        displayName: transitionPreview.title,
+      }
+    : null,
+  onComplete: async (targetPageId) => {
+    // Switch to target page using usePageSwitch
+    await switchToPage(targetPage);
+    // Clear transition state
+    setTransitionPreview(null);
+  },
+  preload: {
+    preloadedUrls: preloadOrchestrator.preloadedUrls,
+    getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+    getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,  // Instant blob URL lookup
+  },
+});
+```
+
+**Key Parameters:**
+
+| Parameter | Purpose |
+|-----------|---------|
+| `storageKey` | Raw storage path for cache lookup (independent of presigned URL signature) |
+| `getReadyBlobUrl` | O(1) instant blob URL lookup by storage key |
+| `getCachedBlobUrl` | Cache API lookup (~5ms) for post-refresh scenarios |
+| `preloadedUrls` | Set of URLs that have been preloaded |
+
+**Video Source Resolution Order:**
+1. `getReadyBlobUrl(storageKey)` - instant (same session)
+2. `getCachedBlobUrl(storageKey)` - Cache API (post-refresh)
+3. `getReadyBlobUrl(resolvedUrl)` - fallback
+4. `getCachedBlobUrl(resolvedUrl)` - fallback
+5. Network fetch (last resort)
+
+---
+
+## Save Workflow
+
+### Environment Model
+
+The constructor implements a dev → stage → production publishing flow:
+
+```
+┌─────────────────┐     Save to Stage     ┌─────────────────┐     Publish     ┌─────────────────┐
+│   dev (edit)    │ ───────────────────── │  stage (review) │ ─────────────── │   production    │
+└─────────────────┘                       └─────────────────┘                 └─────────────────┘
+        ▲
+        │
+   Constructor
+     edits here
+```
+
+- **Save** - Saves current page to the dev environment
+- Save and Save to Stage buttons reserve their timestamp subtitle row and share
+  the same compact control height, so `Just now`/last-stage status text does not
+  misalign the toolbar.
+- **Duplicate Page** - Saves the active dev page, then immediately creates a new
+  independent copy as the last page with copied settings and elements
+- **Delete Page** - Confirms and deletes the active dev page, then selects the
+  next page in presentation order when available
+- **Save to Stage** - Copies ALL dev content to stage for review (calls `POST /publish/save-to-stage`)
+- **Publish** - Copies stage content to production (done from project workspace page)
+
+### Save Function (to Dev)
+
+```typescript
+const saveConstructor = async () => {
+  setSaving(true);
+
+  try {
+    // Serialize elements to JSON
+    const ui_schema_json = JSON.stringify({
+      elements: elements,
+    });
+
+    // Update tour page via API (always saves to dev environment)
+    await dispatch(tourPagesActions.update({
+      id: activePageId,
+      data: {
+        ui_schema_json,
+        background_image_url: backgroundImageUrl,
+        background_video_url: backgroundVideoUrl,
+        background_audio_url: backgroundAudioUrl,
+      },
+    }));
+
+    // Reload data to refresh
+    await loadData();
+
+    setSuccessMessage('Saved successfully');
+  } catch (error) {
+    setErrorMessage('Failed to save');
+  } finally {
+    setSaving(false);
+  }
+};
+```
+
+### Save to Stage Function
+
+**Note:** Save to Stage is **non-blocking** - the API returns immediately while the copy operation continues in the background.
+
+```typescript
+const saveToStage = async () => {
+  if (!projectId) {
+    onError?.('Project ID is required to save to stage.');
+    return;
+  }
+
+  // First save current work to dev
+  await saveConstructor();
+
+  try {
+    setIsSavingToStage(true);
+
+    // Non-blocking: returns immediately, copy runs in background
+    await axios.post('/publish/save-to-stage', { projectId });
+
+    onSuccess?.('Saved to stage.');
+  } catch (error) {
+    const message = error?.response?.data?.message || error?.message || 'Failed to save to stage.';
+    onError?.(message);
+  } finally {
+    setIsSavingToStage(false);
+  }
+};
+```
+
+### Data Persistence
+
+| Field | Storage | Environment |
+|-------|---------|-------------|
+| Elements | `tour_page.ui_schema_json` (JSON string) | dev (edited), stage/prod (copied) |
+| Navigation | `tour_page.ui_schema_json` (targetPageSlug) | dev (edited), stage/prod (copied) |
+| Transitions | `tour_page.ui_schema_json` (transitionVideoUrl) | dev (edited), stage/prod (copied) |
+| Background image | `tour_page.background_image_url` | dev (edited), stage/prod (copied) |
+| Background video | `tour_page.background_video_url` | dev (edited), stage/prod (copied) |
+| Background 360/embed | `tour_page.background_embed_url` | dev (edited), stage/prod (copied) |
+| Background video settings | `tour_page.background_video_*` (autoplay, loop, muted, start_time, end_time) | dev (edited), stage/prod (copied) |
+| Background audio | `tour_page.background_audio_url` | dev (edited), stage/prod (copied) |
+| Audio tracks | `project_audio_tracks` table | dev (edited), stage/prod (copied) |
+
+**Note:** All element data, navigation links, and transitions are stored directly in `ui_schema_json`. No separate tables are used.
+
+### Page Duplication
+
+The constructor supports one-click duplication for pages in the dev environment:
+
+1. Duplicate saves the active page first so the new page matches the current
+   constructor state.
+2. The constructor calls `POST /api/tour_pages/:id/duplicate` with a generated
+   copy name and slug.
+3. The backend duplicates the page record, appends it at the end of the
+   presentation order, deep-copies `ui_schema_json`, and regenerates element and
+   nested item IDs.
+4. Asset URLs, transition URLs, and navigation `targetPageSlug` values are
+   preserved. The duplicated page is selected after reload and is independent from
+   the source page.
+
+Duplication is dev-only. Stage and production receive duplicated pages only
+through Save to Stage and Publish.
+
+### Page Deletion
+
+The constructor toolbar exposes a delete action for the active page when the
+user has `DELETE_TOUR_PAGES`. Deletion uses the same `DELETE /api/tour_pages/:id`
+endpoint as the Pages & Transitions page, but shows a confirmation modal before
+calling the API. After deletion, the constructor invalidates tour page queries,
+selects the next page in display order, or clears the editor when no pages
+remain.
+
+**Backend Publish Flow:**
+- Save to Stage (non-blocking): `POST /publish/save-to-stage` → `PublishService.saveToStage()` → `copyEnvironment(dev, stage)` (runs in background)
+- Publish to Prod (blocking): `POST /publish` → `PublishService.publishToProduction()` → `copyEnvironment(stage, production)`
+
+The `copyEnvironment` method:
+1. Fetches all `tour_pages` and `project_audio_tracks` from source environment
+2. Hard-deletes existing records in target environment (`force: true` for paranoid models)
+3. Bulk creates cloned records with target environment
+4. Preserves slugs and `targetPageSlug` references (consistent across environments)
+
+---
+
+## State Management
+
+State is distributed across the main component and specialized hooks.
+
+### Hook-Managed State
+
+| Hook | State Managed |
+|------|---------------|
+| `useConstructorElements` | `elements`, `selectedElementId`, `selectedElement`, constructor-local element clipboard, `galleryCards`, `galleryInfoSpans`, `carouselSlides` |
+| `useConstructorPageActions` | `isSaving`, `isSavingToStage`, `isCreatingPage`, `isDuplicatingPage`, page save/create/duplicate API calls |
+| `useTransitionPreview` | `transitionPreview`, `pendingNavigationPageId` |
+| `useCanvasElapsedTime` | `canvasElapsedSec` |
+| `useCanvasElementDrag` | Drag state for element positioning |
+| `useMediaDurationProbe` | Media duration cache with `getDuration`, `getDurationNote` |
+| `useIconPreload` | `preloadedIconUrlMap` |
+| `useDraggable` | Panel positions (controls, menu, editor) |
+| `usePageSwitch` | `currentBgImageUrl`, `currentBgVideoUrl`, `currentBgAudioUrl`, `previousBgImageUrl`, `isSwitching`, `isNewBgReady` |
+
+### Local Component State
+
+```typescript
+// Page management
+const [pages, setPages] = useState<TourPage[]>([]);
+const [activePageId, setActivePageId] = useState('');
+const [isCreatePageModalActive, setIsCreatePageModalActive] = useState(false);
+const [isDeletePageModalActive, setIsDeletePageModalActive] = useState(false);
+const [isDeletingPage, setIsDeletingPage] = useState(false);
+
+// Background URLs (storage paths for editing)
+const [backgroundImageUrl, setBackgroundImageUrl] = useState('');
+const [backgroundVideoUrl, setBackgroundVideoUrl] = useState('');
+const [backgroundAudioUrl, setBackgroundAudioUrl] = useState('');
+
+// UI state
+const [constructorInteractionMode, setConstructorInteractionMode] =
+  useState<'edit' | 'interact'>('edit');
+const [selectedMenuItem, setSelectedMenuItem] = useState<EditorMenuItem>('none');
+const [isMenuOpen, setIsMenuOpen] = useState(false);
+const [isEditorCollapsed, setIsEditorCollapsed] = useState(false);
+const [elementEditorTab, setElementEditorTab] = useState<'general' | 'css' | 'effects'>('general');
+
+// Loading and messages
+const [isLoading, setIsLoading] = useState(true);
+const [errorMessage, setErrorMessage] = useState('');
+const [successMessage, setSuccessMessage] = useState('');
+
+// Element defaults (loaded from project_element_defaults)
+const [uiElementDefaultsByType, setUiElementDefaultsByType] = useState<
+  Partial<Record<CanvasElementType, Partial<CanvasElement>>>
+>({});
+```
+
+### Refs
+
+```typescript
+// DOM references
+const canvasRef = useRef<HTMLDivElement>(null);
+const elementEditorRef = useRef<HTMLDivElement>(null);
+const transitionVideoRef = useRef<HTMLVideoElement | null>(null);
+
+// Page initialization tracking
+const lastInitializedPageIdRef = useRef<string | null>(null);
+const didSetInitialCanvasFocus = useRef(false);
+const selectedElementIdRef = useRef<string>('');
+```
+
+---
+
+## Element CRUD Operations
+
+Element CRUD operations are managed by the `useConstructorElements` hook.
+
+### Hook Usage
+
+```typescript
+const {
+  elements,
+  setElements,
+  selectedElementId,
+  selectedElement,
+  copiedElement,
+  canPasteElement,
+  selectElement,
+  clearSelection,
+  addElement,
+  updateSelectedElement,
+  removeSelectedElement,
+  copySelectedElement,
+  pasteCopiedElement,
+  galleryCards,       // { add, update, remove } for gallery cards
+  galleryInfoSpans,   // { add, update, remove } for info span badges
+  carouselSlides,     // { add, update, remove } for carousel slides
+  updateElementPosition,
+  normalizeNavigationType,  // Convert between navigation_next/navigation_prev
+} = useConstructorElements({
+  initialElements: [],
+  elementDefaultsByType: uiElementDefaultsByType,
+  allowedNavigationTypes,
+  initialSelectedElementId: elementIdFromRoute,  // Route parameter support
+  onElementSelected: () => setSelectedMenuItem('none'),
+  onSelectionCleared: () => setSelectedMenuItem('none'),
+  onElementAdded: () => setSuccessMessage('Element added.'),
+  onElementRemoved: () => setSuccessMessage('Element removed.'),
+  onElementCopied: () => setSuccessMessage('Element copied.'),
+  onElementPasted: () => setSuccessMessage('Element pasted.'),
+});
+```
+
+### Element Copy/Paste
+
+The constructor supports separate Copy and Paste actions for UI elements in edit
+mode. Copy stores the selected element in a constructor-local clipboard. The
+clipboard survives page switches inside the same constructor session, so an
+element can be copied from one page and pasted into another page in the same
+presentation.
+
+Paste appends a new independent element to the active page's `elements` array
+and selects it for editing. The clone preserves all non-identity settings from
+the source element, including position, dimensions, navigation targets, links,
+media URLs, transition settings, effects, and CSS styles. Only instance IDs are
+regenerated:
+
+- Element `id`
+- `galleryCards[].id`
+- `galleryInfoSpans[].id`
+- `carouselSlides[].id`
+- `infoPanelSections[].id`
+- `infoPanelSections[].spans[].id`
+- `infoPanelSections[].images[].id`
+
+Pasted elements are not auto-saved. They become persistent when the existing
+Save or Save to Stage flow serializes the active page's `elements` into
+`tour_pages.ui_schema_json`. The constructor keeps a synchronous latest-elements
+reference so a pasted element is included even when the user clicks Save or Stage
+immediately after Paste, before React has completed a visible re-render.
+
+The main constructor toolbar exposes dedicated element Copy and Paste buttons in
+an `Elements actions` group. Page selector, page reorder, new page, duplicate,
+delete, and background controls are kept in a separate `Page actions` group so
+page-level and element-level copy controls are visually distinct. Copy is
+enabled when an element is selected. Paste is enabled when the constructor
+clipboard contains an element, including after switching to another page in the
+same presentation. Keyboard shortcuts are also available in edit mode:
+
+- `Cmd/Ctrl + C` copies the selected element
+- `Cmd/Ctrl + V` pastes the copied element into the active page
+
+Shortcuts are ignored while typing in inputs, textareas, selects, or
+contenteditable fields so native text editing behavior is preserved.
+
+### Create Element
+
+Element creation is a two-step process: create base element, then merge with project defaults.
+
+```typescript
+// Inside useConstructorElements hook
+const addElement = (type: CanvasElementType) => {
+  // Step 1: Create base element with hardcoded defaults
+  const baseElement = createDefaultElement(type, elements.length);
+
+  // Step 2: Merge with project-specific defaults from project_element_defaults
+  const newElement = mergeElementWithDefaults(
+    baseElement,
+    elementDefaultsByType[type],  // Project defaults loaded at startup
+  );
+
+  setElements([...elements, newElement]);
+  selectElement(newElement.id);
+};
+
+// createDefaultElement provides structure-specific defaults (gallery cards, carousel slides, etc.)
+// mergeElementWithDefaults applies styling defaults (colors, fonts, sizes) from project settings
+```
+
+**Note:** The `uiElementDefaultsByType` map is populated during constructor initialization by fetching `/api/project-element-defaults?projectId=xxx` and normalizing the response with `buildElementDefaultsMap()`.
+
+### Load Elements (from ui_schema_json)
+
+When loading existing elements from a page, the merge uses `preferElementValues: true` to preserve saved values:
+
+```typescript
+// In the activePage useEffect
+const normalizedElements = schema.elements.map((item) => {
+  const normalizedElement = { /* normalize fields from JSON */ };
+
+  // Merge with defaults, but PREFER existing element values
+  return mergeElementWithDefaults(
+    normalizedElement,
+    uiElementDefaultsByType[elementType],
+    { preferElementValues: true }  // Key difference from create
+  );
+});
+```
+
+**Merge Behavior:**
+- **Creating new elements**: Defaults override base element (project styling applied)
+- **Loading existing elements**: Element values preserved, defaults only fill empty/null fields
+- **Style properties**: If element has empty/null/undefined style prop, use default value
+
+### Update Element
+
+```typescript
+// Via hook
+updateSelectedElement({ label: 'New Label' });
+
+// Or update any element by ID
+updateElement(elementId, { xPercent: 50, yPercent: 50 });
+```
+
+### Delete Element
+
+```typescript
+// Via hook - removes selected element and clears selection
+removeSelectedElement();
+```
+
+---
+
+## Page Management
+
+Page operations are managed by the `useConstructorPageActions` hook.
+
+### Hook Usage
+
+```typescript
+const {
+  isSaving,
+  isSavingToStage,
+  isCreatingPage,
+  saveConstructor,
+  saveToStage,
+  createPage,
+} = useConstructorPageActions({
+  projectId,
+  pages,
+  activePage,
+  activePageId,
+  elements,
+  backgroundImageUrl,
+  backgroundVideoUrl,
+  backgroundAudioUrl,
+  onReload: loadData,
+  onSetActivePageId: setActivePageId,
+  onError: setErrorMessage,
+  onSuccess: setSuccessMessage,
+});
+```
+
+### Create Page
+
+Pages are always created in the **dev** environment. They must be promoted to stage via "Save to Stage" and then published to production.
+
+```typescript
+// Via hook - handles loading state, API call, and reload
+await createPage();
+```
+
+### Switch Page
+
+Page switching uses `usePageSwitch` for smooth background transitions:
+
+```typescript
+const switchToPage = useCallback(async (page: TourPage | null) => {
+  // Update storage path state for editing/saving
+  setBackgroundImageUrl(page?.background_image_url || '');
+  setBackgroundVideoUrl(page?.background_video_url || '');
+  setBackgroundAudioUrl(page?.background_audio_url || '');
+
+  // Use hook to resolve blob URLs and switch with smooth transition
+  await pageSwitch.switchToPage(
+    page ? {
+      id: page.id,
+      background_image_url: page.background_image_url,
+      background_video_url: page.background_video_url,
+      background_audio_url: page.background_audio_url,
+    } : null,
+    () => setActivePageId(page?.id || ''),
+  );
+}, [pageSwitch]);
+```
+
+### Reorder Pages
+
+The constructor toolbar provides compact up/down arrow buttons next to the page
+selector. The page dropdown labels include an explicit ordinal prefix
+(`1. Page name`, `2. Page name`, etc.) so the current order is visible before
+and after a move. The up button is disabled for the first page, the down button
+is disabled for the last page, and both buttons are disabled while a reorder
+request is in flight.
+
+Reordering posts the full ordered page ID list to
+`POST /api/tour_pages/reorder`, which updates only `sort_order` for pages in
+the dev environment. The active page remains selected after the query cache is
+invalidated and pages are reloaded.
+
+Runtime presentations use the same `sort_order`; the first page after sorting
+is the presentation entry page. Stage receives reordered dev pages only after
+Save to Stage, and production receives reordered stage pages only after Publish.
+
+The reorder endpoint intentionally rejects non-dev environments. Users cannot
+directly reorder stage or production pages from the constructor; those
+environments are updated only by the existing promotion flow.
+
+---
+
+## Icon Preloading
+
+Icon preloading is managed by the `useIconPreload` hook.
+
+### Hook Usage
+
+```typescript
+const iconPreloadTargets = useMemo(() => {
+  const preloadableTypes: CanvasElementType[] = [
+    'navigation_next', 'navigation_prev', 'tooltip', 'description',
+  ];
+  return elements
+    .filter(el => preloadableTypes.includes(el.type) && Boolean(el.iconUrl))
+    .map(el => resolveAssetPlaybackUrl(el.iconUrl))
+    .filter(Boolean);
+}, [elements]);
+
+const { preloadedUrlMap: preloadedIconUrlMap } = useIconPreload({
+  iconUrls: iconPreloadTargets,
+  enabled: !isLoading,
+});
+```
+
+### Page Image Preloading
+
+Page backgrounds and element icons are preloaded by `usePreloadOrchestrator` and served as instant blob URLs. The `usePageSwitch` hook handles smooth transitions between pages by:
+
+1. Resolving blob URLs from preload cache
+2. Pre-decoding images before display
+3. Managing previous/current background overlay during transitions
+
+---
+
+## Key Files Reference
+
+| File | Purpose |
+|------|---------|
+| `pages/constructor.tsx` | Main constructor page component (orchestration layer) |
+| `types/constructor.ts` | TypeScript types for elements, normalization utilities, and grouped props for ElementEditorPanel |
+
+### Constructor-Specific Hooks
+
+| File | Purpose |
+|------|---------|
+| `hooks/useConstructorElements.ts` | Element CRUD, defaults merging, nested item helpers, latest-elements ref, and constructor-local element clipboard |
+| `hooks/useConstructorPageActions.ts` | Page save/create/duplicate and Save to Stage operations |
+| `hooks/useTransitionPreview.ts` | Transition preview state management |
+| `hooks/useCanvasElapsedTime.ts` | Canvas elapsed time tracking for element visibility |
+| `hooks/useCanvasElementDrag.ts` | Element dragging with percentage positioning |
+| `hooks/useMediaDurationProbe.ts` | Media duration detection with caching |
+| `hooks/useIconPreload.ts` | Icon preloading for smooth rendering |
+| `hooks/useOutsideClick.ts` | Outside click detection for deselection |
+| `hooks/useDraggable.ts` | Draggable panel positioning |
+
+### Constructor Components
+
+| File | Purpose |
+|------|---------|
+| `components/Constructor/CanvasBackground.tsx` | Background image/video/audio rendering |
+| `components/Constructor/CanvasElement.tsx` | Canvas element rendering |
+| `components/Constructor/ConstructorToolbar.tsx` | Floating main toolbar with mode, Page actions, Elements actions, Save, Stage, Exit, and Collapse controls |
+| `components/Constructor/ConstructorMenu.tsx` | Legacy/collapsible menu component retained for compatibility |
+| `components/Constructor/ConstructorControlsPanel.tsx` | Legacy/secondary controls panel |
+| `components/Constructor/ElementEditorPanel.tsx` | Element editor panel with tabs |
+| `components/Constructor/ElementEditorHeader.tsx` | Editor header with collapse/remove controls that do not start panel drag |
+| `components/Constructor/TransitionPreviewOverlay.tsx` | Transition video overlay |
+| `components/Constructor/PageSelector.tsx` | Page dropdown selector with ordinal labels and toolbar sizing support |
+| `components/Constructor/InteractionModeToggle.tsx` | Edit/Interact mode toggle with compact toolbar layout |
+| `components/Constructor/AssetSelectCompact.tsx` | Compact asset dropdown |
+| `components/Constructor/BackgroundSettingsEditor.tsx` | Background media settings form |
+| `components/Constructor/CreateTransitionForm.tsx` | Transition creation form |
+| `components/Constructor/MenuActionButton.tsx` | Menu action button component |
+
+### Helper Libraries
+
+| File | Purpose |
+|------|---------|
+| `lib/elementDefaults.ts` | Element type labels, create functions, type guards |
+| `lib/constructorHelpers.ts` | Asset helpers (getAssetLabel, getAssetSourceValue, clamp) |
+| `lib/navigationHelpers.ts` | Navigation target resolution, direction helpers |
+| `lib/mediaHelpers.ts` | Media duration and format helpers |
+| `lib/extractPageLinks.ts` | Extract pageLinks and preloadElements from ui_schema_json |
+| `lib/elementStyles.ts` | Build CSS styles from element properties |
+| `lib/elementEffects.ts` | Build animation and interaction effects (hover, focus, active, appear) |
+
+### UI Element Components
+
+| File | Purpose |
+|------|---------|
+| `components/UiElements/GalleryCarouselOverlay.tsx` | Fullscreen carousel overlay for gallery cards with draggable navigation buttons |
+| `components/UiElements/UiElementRenderer.tsx` | Generic element renderer for runtime/preview |
+| `components/UiElements/ElementPreview.tsx` | Element preview component |
+
+### Shared Runtime Hooks
+
+| File | Purpose |
+|------|---------|
+| `hooks/usePreloadOrchestrator.ts` | Asset preloading with blob URL caching |
+| `hooks/usePageSwitch.ts` | Smooth page transitions with preload integration |
+| `hooks/useTransitionPlayback.ts` | Transition video playback |
+| `hooks/useBackgroundTransition.ts` | Background transition clearing |
+| `hooks/useBackgroundVideoPlayback.ts` | Background video playback with time control |
+
+### Other Files
+
+| File | Purpose |
+|------|---------|
+| `config/preload.config.ts` | Preload settings: priority weights, maxDepth, asset field names |
+| `components/Assets/useAssetUploader.ts` | File upload |
+| `stores/tour_pages/tour_pagesSlice.ts` | Page state management |
+| `stores/assets/assetsSlice.ts` | Asset state management |
+| `pages/element-type-defaults.tsx` | Global element defaults admin page |
+| `pages/element-type-defaults/[id].tsx` | Global element default editor |
+| `pages/project-element-defaults.tsx` | Project element defaults list |
+| `pages/project-element-defaults/[id].tsx` | Project element default editor |
+
+### Shared ElementSettings Components
+
+These components are shared across global defaults, project defaults, and constructor pages:
+
+| File | Purpose |
+|------|---------|
+| `components/ElementSettings/index.ts` | Barrel exports for all components |
+| `components/ElementSettings/types.ts` | Shared types (`SettingsContext`, validation helpers) |
+| `components/ElementSettings/useElementSettingsForm.ts` | Form state management hook for defaults pages |
+| `components/ElementSettings/ElementSettingsTabs.tsx` | Tab navigation (full-size for admin pages) |
+| `components/ElementSettings/StyleSettingsSection.tsx` | CSS styling fields (full-size for admin pages) |
+| `components/ElementSettings/StyleSettingsSectionCompact.tsx` | CSS styling fields (compact for constructor) |
+| `components/ElementSettings/CommonSettingsSection.tsx` | Label, position, appear timing fields |
+| `components/ElementSettings/NavigationSettingsSection.tsx` | Navigation element settings |
+| `components/ElementSettings/TooltipSettingsSection.tsx` | Tooltip element settings |
+| `components/ElementSettings/DescriptionSettingsSection.tsx` | Description element settings |
+| `components/ElementSettings/MediaSettingsSection.tsx` | Video/audio player settings |
+| `components/ElementSettings/GallerySettingsSection.tsx` | Gallery cards editor |
+| `components/ElementSettings/CarouselSettingsSection.tsx` | Carousel slides editor |
+
+**Context-aware rendering**: Components accept a `context` prop (`'global'`, `'project'`, or `'constructor'`) to render appropriate UI (e.g., asset selectors in constructor vs plain text inputs in admin pages).
+
+---
+
+## Limitations
+
+### Not Implemented
+
+- Undo/redo history
+- Element grouping
+- Snap-to-grid
+- Alignment tools
+- Element locking
+- Animation timeline editor
+- Element rotation UI
+
+### Workarounds
+
+| Feature | Workaround |
+|---------|------------|
+| Z-index | Set via `zIndex` property in element |
+| Rotation | Set via CSS `transform` in style_json |
+| Grouping | Create container element manually |
+
+---
+
+## Integration Points
+
+| System | Integration |
+|--------|-------------|
+| Assets API | Load project assets for selectors |
+| Tour Pages API | CRUD page operations (always on dev environment) |
+| Project Element Defaults API | **Constructor uses this** - Project-specific defaults (`/api/project-element-defaults?projectId=xxx`) |
+| Element Type Defaults API | Global platform defaults - used for snapshotting, not directly by constructor (`/api/element-type-defaults`) |
+| Publish API | Save to Stage functionality (`POST /publish/save-to-stage`) |
+| Preload System | Asset preloading via `usePreloadOrchestrator` (S3 direct download → Cache API → blob URLs) |
+| Page Switch | Smooth transitions via `usePageSwitch` (blob URL resolution, background overlay during switch) |
+| Runtime | Constructor output displayed in runtime (stage/production environments) |
+
+**Note:** Navigation and transitions are stored directly in `tour_pages.ui_schema_json` (as `targetPageSlug` and `transitionVideoUrl`). No separate API tables exist for these.
+
+### Element Defaults Hierarchy (Three-Tier System)
+
+The system uses a three-tier defaults cascade:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Tier 1: element_type_defaults (Global)                    │
+│  Field: default_settings_json                              │
+│  Seeded: 12 predefined element types                       │
+│  Admin: /element-type-defaults                             │
+└────────────────────────────────────────────────────────────┘
+                        ↓ (snapshot on project creation)
+┌────────────────────────────────────────────────────────────┐
+│  Tier 2: project_element_defaults (Project-Specific)       │
+│  Field: settings_json                                      │
+│  Created: Auto-snapshotted when project is created         │
+│  Admin: /project-element-defaults?projectId=xxx            │
+└────────────────────────────────────────────────────────────┘
+                        ↓ (merge on element creation)
+┌────────────────────────────────────────────────────────────┐
+│  Tier 3: tour_pages.ui_schema_json (Instance)              │
+│  Each element has its own settings in elements[]           │
+│  Edited: Constructor page                                  │
+└────────────────────────────────────────────────────────────┘
+```
+
+**How it works:**
+
+1. **On project creation**: Global defaults (`element_type_defaults`) are automatically snapshotted to project defaults (`project_element_defaults`)
+2. **Constructor loads project defaults**: Fetches `/api/project-element-defaults?projectId=xxx` (NOT global defaults)
+3. **On element creation**: `createDefaultElement()` creates base element, then `mergeElementWithDefaults()` applies project-specific settings
+4. **Element stored**: Final element with all settings saved in `tour_pages.ui_schema_json`
+
+**Key utilities:**
+
+```typescript
+// types/constructor.ts - API response normalization
+normalizeElementDefault(row) → NormalizedElementDefault
+buildElementDefaultsMap(defaults) → Record<CanvasElementType, Partial<CanvasElement>>
+
+// lib/elementDefaults.ts - Element creation and merging
+createDefaultElement(type, index) → CanvasElement
+mergeElementWithDefaults(element, defaults, options) → CanvasElement
+isCanvasElementType(value) → boolean
+ELEMENT_TYPE_LABELS → Record<CanvasElementType, string>
+```
+
+**Merge behavior**: The `mergeElementWithDefaults()` function applies project defaults, with element values taking precedence over defaults (except for empty/null values which inherit from defaults).
+
+This allows each project to customize element appearance while maintaining platform-wide base settings.
+
+### Grouped Props for ElementEditorPanel
+
+The `types/constructor.ts` file defines grouped prop interfaces for the `ElementEditorPanel` component, improving type safety and code organization:
+
+```typescript
+// Editor layout props
+interface EditorLayoutProps {
+  elementEditorRef: React.RefObject<HTMLDivElement | null>;
+  position: { x: number; y: number };
+  isCollapsed: boolean;
+  onToggleCollapse: () => void;
+  onDragStart: (event: React.MouseEvent) => void;
+}
+
+// Editor state props
+interface EditorStateProps {
+  title: string;
+  activeTab: 'general' | 'css' | 'effects';
+  onTabChange: (tab: 'general' | 'css' | 'effects') => void;
+}
+
+// Selected element props
+interface EditorElementProps {
+  selectedElement: CanvasElement | null;
+  selectedMenuItem: 'none' | 'background_image' | 'background_video' | 'background_audio' | 'create_transition';
+  onRemoveElement: () => void;
+  onUpdateElement: (patch: Partial<CanvasElement>) => void;
+}
+
+// Background settings props
+interface EditorBackgroundProps { ... }
+
+// Transition creation props
+interface EditorTransitionProps { ... }
+
+// Duration notes props
+interface EditorDurationNotesProps { ... }
+
+// Asset options props
+interface EditorAssetOptionsProps { ... }
+
+// Navigation settings props
+interface EditorNavigationProps { ... }
+
+// Gallery/Carousel collection operations
+interface EditorCollectionOpsProps {
+  galleryCards: { add, update, remove };
+  galleryInfoSpans: { add, update, remove };
+  carouselSlides: { add, update, remove };
+}
+
+// Media utilities
+interface EditorMediaUtilsProps {
+  getDuration: (url: string) => number | undefined;
+}
+```
diff --git a/frontend/docs/context-module.md b/frontend/docs/context-module.md
new file mode 100644
index 0000000..a0e752f
--- /dev/null
+++ b/frontend/docs/context-module.md
@@ -0,0 +1,1100 @@
+# Frontend Context Module
+
+## Overview
+
+The Context module provides **React Context-based state management** for cross-cutting concerns that need to be shared across the component tree without prop drilling. Currently, the module contains a single context for managing download/preload progress in the PWA offline system.
+
+**Location:** `frontend/src/context/`
+
+**Total Files:** 1 file (~256 LOC)
+
+---
+
+## Architecture
+
+```
+frontend/src/context/
+└── DownloadContext.tsx   (256 LOC)  # Download progress state management
+
+Related Files:
+├── lib/offline/DownloadEventBus.ts  (180 LOC)  # Event emitter for download events
+├── hooks/usePreloadProgress.ts      (221 LOC)  # Hook-based alternative
+├── config/offline.config.ts         (53 LOC)   # Event names, IndexedDB, cache settings
+├── config/preload.config.ts         (95 LOC)   # Priority weights, auto-cleanup timeouts
+├── types/offline.ts                 (195 LOC)  # Type definitions
+│
+└── components/Offline/
+    ├── DownloadProgressPanel.tsx    (194 LOC)  # Progress UI with job list
+    ├── OfflineStatusIndicator.tsx   (62 LOC)   # Status badge (online/offline/syncing)
+    ├── OfflineToggle.tsx            (150 LOC)  # Download toggle with storage checks
+    └── StorageUsageDisplay.tsx      (125 LOC)  # Storage quota UI with persistence
+```
+
+---
+
+## DownloadContext (`DownloadContext.tsx`)
+
+**Purpose:** Manage download job state and progress for PWA asset preloading.
+
+**Lines:** 256 LOC
+
+### Context State Interface
+
+```typescript
+interface DownloadState {
+  jobs: PreloadJob[];        // All tracked download jobs
+  activeCount: number;       // Jobs currently downloading/queued
+  completedCount: number;    // Jobs completed successfully
+  errorCount: number;        // Jobs that failed
+  totalProgress: number;     // Overall progress percentage (0-100)
+  isDownloading: boolean;    // True if any job is active
+}
+```
+
+### Context Value Interface
+
+```typescript
+interface DownloadContextValue extends DownloadState {
+  clearJob: (id: string) => void;      // Remove a specific job
+  clearAllCompleted: () => void;       // Clear all completed jobs
+  clearAllErrors: () => void;          // Clear all errored jobs
+  clearAll: () => void;                // Clear all jobs
+}
+```
+
+### PreloadJob Interface
+
+```typescript
+interface PreloadJob {
+  id: string;                          // Unique job identifier
+  assetId: string;                     // Asset being downloaded
+  url: string;                         // Download URL
+  filename: string;                    // Display filename
+  progress: number;                    // 0-100 percent
+  status: PreloadJobStatus;            // 'queued' | 'downloading' | 'completed' | 'error' | 'paused'
+  bytesLoaded: number;                 // Bytes downloaded
+  totalBytes: number;                  // Total file size
+  pageId?: string;                     // Associated tour page
+  variantType?: AssetVariantType;      // thumbnail, preview, webp, etc.
+  assetType?: AssetType;               // image, video, audio, transition
+  error?: string;                      // Error message if failed
+  addedAt: number;                     // Timestamp added to queue
+  startedAt?: number;                  // Timestamp download started
+  completedAt?: number;                // Timestamp completed
+}
+```
+
+---
+
+## Provider Implementation
+
+### DownloadProvider Component
+
+```typescript
+export function DownloadProvider({ children }: DownloadProviderProps) {
+  const [jobs, setJobs] = useState<PreloadJob[]>([]);
+
+  // Subscribe to DownloadEventBus events
+  useEffect(() => {
+    const handleStart = (data: PreloadStartEvent) => {
+      // Create new job from event data
+    };
+    return downloadEventBus.on(OFFLINE_CONFIG.events.preloadStart, handleStart);
+  }, []);
+
+  // Similar subscriptions for progress, complete, error events...
+
+  // Computed values with useMemo
+  const value = useMemo<DownloadContextValue>(() => ({
+    jobs,
+    activeCount: jobs.filter(j => j.status === 'downloading' || j.status === 'queued').length,
+    completedCount: jobs.filter(j => j.status === 'completed').length,
+    errorCount: jobs.filter(j => j.status === 'error').length,
+    totalProgress: calculateTotalProgress(jobs),
+    isDownloading: activeCount > 0,
+    clearJob,
+    clearAllCompleted,
+    clearAllErrors,
+    clearAll,
+  }), [jobs, clearJob, clearAllCompleted, clearAllErrors, clearAll]);
+
+  return (
+    <DownloadContext.Provider value={value}>
+      {children}
+    </DownloadContext.Provider>
+  );
+}
+```
+
+### Event Handling
+
+The provider subscribes to four events from `DownloadEventBus`:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Event Flow                               │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 usePreloadOrchestrator                      │
+│                 DownloadManager                             │
+│                 (Emit events via downloadEventBus)          │
+└─────────────────────────────────────────────────────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        ▼                     ▼                     ▼
+┌───────────────┐     ┌───────────────┐     ┌───────────────┐
+│ preloadStart  │     │preloadProgress│     │preloadComplete│
+│               │     │               │     │               │
+│ Create new    │     │ Update        │     │ Mark complete │
+│ job entry     │     │ progress %    │     │ Auto-remove   │
+│               │     │ bytesLoaded   │     │ after 3s      │
+└───────────────┘     └───────────────┘     └───────────────┘
+        │                     │                     │
+        └─────────────────────┼─────────────────────┘
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    preloadError                             │
+│                                                             │
+│  Mark job as error, store error message                     │
+│  Auto-remove after 10s                                      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 DownloadContext State                       │
+│                                                             │
+│  jobs[], activeCount, completedCount, errorCount,           │
+│  totalProgress, isDownloading                               │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 Consumer Components                         │
+│                                                             │
+│  DownloadProgressPanel, OfflineStatusIndicator, etc.        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Event Handlers
+
+```typescript
+// Handle preload start - create new job
+const handleStart = (data: PreloadStartEvent) => {
+  const newJob: PreloadJob = {
+    id: data.jobId,
+    assetId: data.assetId,
+    url: data.url,
+    filename: data.url.split('/').pop() || 'unknown',
+    progress: 0,
+    status: 'downloading',
+    bytesLoaded: 0,
+    totalBytes: 0,
+    addedAt: Date.now(),
+    startedAt: Date.now(),
+  };
+
+  setJobs((prev) => {
+    // Avoid duplicates
+    if (prev.some((j) => j.id === data.jobId)) {
+      return prev;
+    }
+    return [...prev, newJob];
+  });
+};
+
+// Handle preload progress - update existing job
+const handleProgress = (data: PreloadProgressEvent) => {
+  setJobs((prev) =>
+    updateJobInArray(prev, data.jobId, {
+      progress: data.progress,
+      bytesLoaded: data.bytesLoaded,
+      totalBytes: data.totalBytes,
+      status: 'downloading',
+    }),
+  );
+};
+
+// Handle preload complete - mark done and auto-remove
+const handleComplete = (data: PreloadCompleteEvent) => {
+  setJobs((prev) =>
+    updateJobInArray(prev, data.jobId, {
+      status: 'completed',
+      progress: 100,
+      completedAt: Date.now(),
+    }),
+  );
+
+  // Auto-remove after 3 seconds
+  setTimeout(() => {
+    setJobs((prev) => prev.filter((j) => j.id !== data.jobId));
+  }, PRELOAD_CONFIG.autoRemove.completedMs);
+};
+
+// Handle preload error - mark failed and auto-remove
+const handleError = (data: PreloadErrorEvent) => {
+  setJobs((prev) =>
+    updateJobInArray(prev, data.jobId, {
+      status: 'error',
+      error: data.error,
+    }),
+  );
+
+  // Auto-remove after 10 seconds
+  setTimeout(() => {
+    setJobs((prev) => prev.filter((j) => j.id !== data.jobId));
+  }, PRELOAD_CONFIG.autoRemove.errorMs);
+};
+```
+
+---
+
+## Consumer Hooks
+
+### useDownloadContext (Required)
+
+```typescript
+export function useDownloadContext(): DownloadContextValue {
+  const context = useContext(DownloadContext);
+  if (!context) {
+    throw new Error(
+      'useDownloadContext must be used within a DownloadProvider',
+    );
+  }
+  return context;
+}
+```
+
+**Usage:**
+
+```typescript
+import { useDownloadContext } from '@/context/DownloadContext';
+
+function MyComponent() {
+  const {
+    jobs,
+    activeCount,
+    completedCount,
+    totalProgress,
+    isDownloading,
+    clearJob,
+    clearAllCompleted,
+  } = useDownloadContext();
+
+  return (
+    <div>
+      {isDownloading && <span>Downloading... {totalProgress}%</span>}
+      <ul>
+        {jobs.map(job => (
+          <li key={job.id}>
+            {job.filename}: {job.progress}%
+            <button onClick={() => clearJob(job.id)}>×</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### useDownloadContextOptional (Safe)
+
+```typescript
+export function useDownloadContextOptional(): DownloadContextValue | null {
+  return useContext(DownloadContext);
+}
+```
+
+**Usage:** For components that may render outside the provider:
+
+```typescript
+function SafeComponent() {
+  const downloadCtx = useDownloadContextOptional();
+
+  // Works even outside DownloadProvider
+  if (downloadCtx?.isDownloading) {
+    return <span>Downloading...</span>;
+  }
+  return null;
+}
+```
+
+---
+
+## Provider Setup
+
+The provider is mounted at the application root in `_app.tsx`:
+
+```typescript
+// pages/_app.tsx
+import { DownloadProvider } from '../context/DownloadContext';
+
+function MyApp({ Component, pageProps }: AppPropsWithLayout) {
+  const getLayout = Component.getLayout || ((page) => page);
+
+  return (
+    <Provider store={store}>
+      <DownloadProvider>
+        {getLayout(
+          <>
+            <Head>
+              {/* Meta tags, favicon, PWA manifest */}
+            </Head>
+            <ErrorBoundary>
+              <Component {...pageProps} />
+            </ErrorBoundary>
+            <IntroGuide steps={steps} stepsEnabled={stepsEnabled} onExit={handleExit} />
+          </>
+        )}
+      </DownloadProvider>
+    </Provider>
+  );
+}
+
+export default appWithTranslation(MyApp);
+```
+
+### Provider Hierarchy
+
+```
+<Provider store={store}>           ← Redux
+  <DownloadProvider>               ← React Context (download progress)
+    {getLayout(                    ← Per-page layout (LayoutAuthenticated/LayoutGuest)
+      <>
+        <Head />                   ← Meta tags, PWA config
+        <ErrorBoundary>
+          <Component />            ← Page component
+        </ErrorBoundary>
+        <IntroGuide />             ← Onboarding tour
+      </>
+    )}
+  </DownloadProvider>
+</Provider>
+```
+
+---
+
+## Related: DownloadEventBus
+
+The context subscribes to events from `DownloadEventBus`, a browser-native event emitter:
+
+```typescript
+// lib/offline/DownloadEventBus.ts
+class DownloadEventBusClass {
+  private listeners: Map<string, Set<EventCallback<unknown>>> = new Map();
+
+  on<K extends keyof EventMap>(event: K, callback: EventCallback<EventMap[K]>): () => void;
+  off<K extends keyof EventMap>(event: K, callback: EventCallback<EventMap[K]>): void;
+  emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+  once<K extends keyof EventMap>(event: K, callback: EventCallback<EventMap[K]>): () => void;
+  removeAllListeners(event?: keyof EventMap): void;
+  listenerCount(event: keyof EventMap): number;
+
+  // Convenience methods
+  emitPreloadStart(data: PreloadStartEvent): void;
+  emitPreloadProgress(data: PreloadProgressEvent): void;
+  emitPreloadComplete(data: PreloadCompleteEvent): void;
+  emitPreloadError(data: PreloadErrorEvent): void;
+  emitProjectProgress(data: ProjectDownloadProgressEvent): void;
+  emitProjectComplete(data: ProjectDownloadCompleteEvent): void;
+  emitQueueUpdate(): void;
+}
+
+export const downloadEventBus = new DownloadEventBusClass();
+```
+
+### Event Types
+
+```typescript
+// Defined in config/offline.config.ts
+export const OFFLINE_CONFIG = {
+  events: {
+    preloadStart: 'asset-preload-start',
+    preloadProgress: 'asset-preload-progress',
+    preloadComplete: 'asset-preload-complete',
+    preloadError: 'asset-preload-error',
+    projectDownloadProgress: 'project-download-progress',
+    projectDownloadComplete: 'project-download-complete',
+    queueUpdate: 'queue-update',
+  },
+  // ...
+};
+```
+
+---
+
+## Related: usePreloadProgress Hook
+
+An alternative hook-based approach that also subscribes to `DownloadEventBus`:
+
+```typescript
+// hooks/usePreloadProgress.ts
+export function usePreloadProgress(): UsePreloadProgressResult {
+  const [jobs, setJobs] = useState<PreloadJob[]>([]);
+
+  // Same event subscription pattern as DownloadContext
+  useEffect(() => {
+    return downloadEventBus.on(
+      OFFLINE_CONFIG.events.preloadStart,
+      handleStart,
+    );
+  }, []);
+
+  // ... similar to DownloadContext
+
+  return {
+    jobs,
+    activeCount,
+    completedCount,
+    errorCount,
+    totalProgress,
+    isActive,
+    clearJob,
+    clearAllCompleted,
+    clearAllErrors,
+  };
+}
+```
+
+### Context vs Hook Comparison
+
+| Aspect | DownloadContext | usePreloadProgress |
+|--------|-----------------|-------------------|
+| **State Sharing** | Shared across tree | Per-component instance |
+| **Deduplication** | Single subscription | Multiple subscriptions |
+| **Use Case** | Global UI (headers) | Local UI (panels) |
+| **Performance** | Better for many consumers | Better for single consumer |
+| **Coupling** | Requires Provider | Standalone |
+
+**Recommendation:** Use `DownloadContext` for shared global state (status indicators in headers), use `usePreloadProgress` for isolated components (embedded progress panels).
+
+---
+
+## Consumer Components
+
+### DownloadProgressPanel
+
+Shows detailed download progress with job list:
+
+```typescript
+import {
+  mdiPause, mdiPlay, mdiClose, mdiCheck, mdiAlertCircle, mdiLoading,
+} from '@mdi/js';
+import Icon from '@mdi/react';
+import { usePreloadProgress } from '../../hooks/usePreloadProgress';
+
+interface DownloadProgressPanelProps {
+  className?: string;
+  maxItems?: number;
+  showWhenEmpty?: boolean;
+}
+
+export function DownloadProgressPanel({
+  className = '',
+  maxItems = 5,
+  showWhenEmpty = false,
+}: DownloadProgressPanelProps) {
+  const {
+    jobs,
+    activeCount,
+    completedCount,
+    errorCount,
+    totalProgress,
+    isActive,
+    clearJob,
+    clearAllCompleted,
+    clearAllErrors,
+  } = usePreloadProgress();
+
+  if (!showWhenEmpty && jobs.length === 0) return null;
+
+  const visibleJobs = jobs.slice(0, maxItems);
+  const hiddenCount = jobs.length - maxItems;
+
+  return (
+    <div className={`bg-white border rounded-lg shadow-lg p-3 min-w-[280px] ${className}`}>
+      {/* Header */}
+      <div className='flex items-center justify-between mb-2 pb-2 border-b'>
+        <span className='text-sm font-medium'>Downloads</span>
+        {isActive && <span className='text-xs text-blue-600'>{activeCount} active</span>}
+        {completedCount > 0 && (
+          <button onClick={clearAllCompleted} className='text-xs text-gray-500'>
+            Clear completed
+          </button>
+        )}
+      </div>
+
+      {/* Overall progress */}
+      {isActive && (
+        <div className='mb-3'>
+          <div className='flex justify-between text-xs text-gray-500 mb-1'>
+            <span>Overall progress</span>
+            <span>{totalProgress}%</span>
+          </div>
+          <div className='w-full h-1.5 bg-gray-200 rounded-full overflow-hidden'>
+            <div className='h-full bg-blue-500' style={{ width: `${totalProgress}%` }} />
+          </div>
+        </div>
+      )}
+
+      {/* Job list */}
+      <div className='space-y-2'>
+        {visibleJobs.map((job) => (
+          <div key={job.id} className='flex items-center gap-2 p-2 bg-gray-50 rounded'>
+            {/* Status icon */}
+            {job.status === 'downloading' && (
+              <Icon path={mdiLoading} size={0.7} className='text-blue-500 animate-spin' />
+            )}
+            {job.status === 'completed' && (
+              <Icon path={mdiCheck} size={0.7} className='text-green-500' />
+            )}
+            {job.status === 'error' && (
+              <Icon path={mdiAlertCircle} size={0.7} className='text-red-500' />
+            )}
+
+            {/* Info */}
+            <div className='flex-1 min-w-0'>
+              <div className='text-xs font-medium truncate'>{job.filename}</div>
+              {job.status === 'downloading' && (
+                <div className='w-full h-1 bg-gray-200 rounded-full mt-1'>
+                  <div className='h-full bg-blue-500' style={{ width: `${job.progress}%` }} />
+                </div>
+              )}
+            </div>
+
+            {/* Close button */}
+            <button onClick={() => clearJob(job.id)} className='p-0.5 text-gray-400'>
+              <Icon path={mdiClose} size={0.5} />
+            </button>
+          </div>
+        ))}
+
+        {hiddenCount > 0 && (
+          <div className='text-xs text-gray-500 text-center py-1'>
+            +{hiddenCount} more items
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### OfflineStatusIndicator
+
+Small badge showing sync status:
+
+```typescript
+import { mdiCloudCheck, mdiCloudOffOutline, mdiCloudSync } from '@mdi/js';
+import Icon from '@mdi/react';
+import { useNetworkAware } from '../../hooks/useNetworkAware';
+import { usePreloadProgress } from '../../hooks/usePreloadProgress';
+
+interface OfflineStatusIndicatorProps {
+  className?: string;
+  showLabel?: boolean;
+  projectId?: string | null;
+}
+
+export function OfflineStatusIndicator({
+  className = '',
+  showLabel = false,
+}: OfflineStatusIndicatorProps) {
+  const { networkInfo } = useNetworkAware();
+  const { isActive, totalProgress } = usePreloadProgress();
+
+  // Determine status
+  let icon = mdiCloudCheck;
+  let label = 'Online';
+  let colorClass = 'text-green-500';
+  let bgClass = 'bg-green-50';
+
+  if (!networkInfo.isOnline) {
+    icon = mdiCloudOffOutline;
+    label = 'Offline';
+    colorClass = 'text-gray-500';
+    bgClass = 'bg-gray-100';
+  } else if (isActive) {
+    icon = mdiCloudSync;
+    label = `Syncing ${totalProgress}%`;
+    colorClass = 'text-blue-500';
+    bgClass = 'bg-blue-50';
+  }
+
+  return (
+    <div
+      className={`flex items-center gap-1.5 px-2 py-1 rounded-full ${bgClass} ${className}`}
+      title={label}
+    >
+      <Icon
+        path={icon}
+        size={0.6}
+        className={`${colorClass} ${isActive ? 'animate-pulse' : ''}`}
+      />
+      {showLabel && (
+        <span className={`text-xs font-medium ${colorClass}`}>{label}</span>
+      )}
+    </div>
+  );
+}
+```
+
+### OfflineToggle
+
+Toggle button for offline download:
+
+```typescript
+import { mdiCloudDownload, mdiCloudCheck, mdiCloudOff, mdiDelete } from '@mdi/js';
+import Icon from '@mdi/react';
+import BaseButton from '../BaseButton';
+import { useOfflineMode } from '../../hooks/useOfflineMode';
+import { useStorageQuota } from '../../hooks/useStorageQuota';
+
+interface OfflineToggleProps {
+  projectId: string | null;
+  projectSlug?: string;
+  projectName?: string;
+  className?: string;
+  showLabel?: boolean;
+  size?: 'small' | 'medium' | 'large';
+}
+
+export function OfflineToggle({
+  projectId,
+  projectSlug,
+  projectName,
+  className = '',
+  showLabel = true,
+  size = 'medium',
+}: OfflineToggleProps) {
+  const {
+    isOfflineCapable,
+    isDownloaded,
+    isDownloading,
+    status,
+    progress,
+    startDownload,
+    pauseDownload,
+    resumeDownload,
+    cancelDownload,
+    deleteOfflineData,
+    estimatedSize,
+    formatSize,
+  } = useOfflineMode({ projectId, projectSlug, projectName });
+
+  const { canStore, isWarning, isCritical } = useStorageQuota();
+
+  if (!isOfflineCapable) return null;
+
+  const handleClick = () => {
+    if (isDownloaded) {
+      if (confirm('Remove offline data for this project?')) {
+        deleteOfflineData();
+      }
+    } else if (isDownloading) {
+      pauseDownload();
+    } else if (status === 'error') {
+      resumeDownload();
+    } else {
+      if (isCritical) {
+        alert('Storage space is critically low.');
+        return;
+      }
+      startDownload();
+    }
+  };
+
+  // Determine icon and label based on status
+  let icon = mdiCloudDownload;
+  let label = 'Download for offline';
+  let color: 'info' | 'success' | 'danger' | 'warning' = 'info';
+
+  if (isDownloaded) {
+    icon = mdiCloudCheck;
+    label = 'Available offline';
+    color = 'success';
+  } else if (isDownloading) {
+    label = `Downloading ${progress}%`;
+  } else if (status === 'error') {
+    icon = mdiCloudOff;
+    label = 'Retry download';
+    color = 'danger';
+  }
+
+  return (
+    <div className={`flex items-center gap-2 ${className}`}>
+      <BaseButton
+        small={size === 'small'}
+        color={color}
+        icon={icon}
+        label={showLabel ? label : undefined}
+        onClick={handleClick}
+        disabled={!canStore(estimatedSize) && !isDownloaded}
+      />
+      {isDownloaded && (
+        <button onClick={() => deleteOfflineData()} title='Remove offline data'>
+          <Icon path={mdiDelete} size={0.7} />
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+### StorageUsageDisplay
+
+Visual storage quota indicator:
+
+```typescript
+import { mdiDatabase } from '@mdi/js';
+import Icon from '@mdi/react';
+import { useStorageQuota } from '../../hooks/useStorageQuota';
+
+interface StorageUsageDisplayProps {
+  className?: string;
+  showDetails?: boolean;
+  compact?: boolean;
+}
+
+export function StorageUsageDisplay({
+  className = '',
+  showDetails = true,
+  compact = false,
+}: StorageUsageDisplayProps) {
+  const {
+    usage,
+    quota,
+    percentUsed,
+    isLoading,
+    isWarning,
+    isCritical,
+    isPersisted,
+    formatSize,
+    requestPersistence,
+  } = useStorageQuota();
+
+  if (isLoading) {
+    return <div className='animate-pulse h-4 bg-gray-200 rounded w-32' />;
+  }
+
+  let barColor = 'bg-blue-500';
+  let textColor = 'text-gray-600';
+
+  if (isCritical) {
+    barColor = 'bg-red-500';
+    textColor = 'text-red-600';
+  } else if (isWarning) {
+    barColor = 'bg-yellow-500';
+    textColor = 'text-yellow-600';
+  }
+
+  return (
+    <div className={`space-y-2 ${className}`}>
+      <div className='flex items-center justify-between'>
+        <div className='flex items-center gap-2'>
+          <Icon path={mdiDatabase} size={0.7} className='text-gray-500' />
+          <span className='text-sm font-medium text-gray-700'>Storage</span>
+        </div>
+        {showDetails && (
+          <span className={`text-xs ${textColor}`}>
+            {formatSize(usage)} / {formatSize(quota)}
+          </span>
+        )}
+      </div>
+
+      <div className='w-full h-2 bg-gray-200 rounded-full overflow-hidden'>
+        <div
+          className={`h-full ${barColor} transition-all duration-300`}
+          style={{ width: `${Math.min(percentUsed, 100)}%` }}
+        />
+      </div>
+
+      {showDetails && (
+        <div className='flex items-center justify-between text-xs'>
+          <span className={textColor}>
+            {isCritical ? 'Storage critically low' :
+             isWarning ? 'Storage running low' :
+             `${Math.round(100 - percentUsed)}% available`}
+          </span>
+          {!isPersisted && (
+            <button onClick={requestPersistence} className='text-blue-500'>
+              Make persistent
+            </button>
+          )}
+          {isPersisted && (
+            <span className='text-green-600'>Persistent storage enabled</span>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Progress Calculation
+
+```typescript
+const calculateTotalProgress = (jobs: PreloadJob[]): number => {
+  if (jobs.length === 0) return 0;
+
+  const activeJobs = jobs.filter(
+    (j) => j.status !== 'completed' && j.status !== 'error',
+  );
+  if (activeJobs.length === 0) return 100;
+
+  const totalBytes = activeJobs.reduce((sum, j) => sum + j.totalBytes, 0);
+  const loadedBytes = activeJobs.reduce((sum, j) => sum + j.bytesLoaded, 0);
+
+  if (totalBytes === 0) {
+    // Fallback to count-based progress
+    const completedCount = jobs.filter((j) => j.status === 'completed').length;
+    return Math.round((completedCount / jobs.length) * 100);
+  }
+
+  return Math.round((loadedBytes / totalBytes) * 100);
+};
+```
+
+---
+
+## Auto-Cleanup
+
+Jobs are automatically removed after completion/error:
+
+```typescript
+// From PRELOAD_CONFIG
+autoRemove: {
+  completedMs: 3000,   // Remove completed jobs after 3 seconds
+  errorMs: 10000,      // Remove error jobs after 10 seconds
+}
+```
+
+This prevents the jobs array from growing indefinitely and provides a brief visual confirmation before cleanup.
+
+---
+
+## Type Definitions
+
+### PreloadJobStatus
+
+```typescript
+type PreloadJobStatus =
+  | 'queued'       // In queue, not yet started
+  | 'downloading'  // Currently downloading
+  | 'completed'    // Successfully completed
+  | 'error'        // Failed with error
+  | 'paused';      // Paused by user
+```
+
+### AssetVariantType
+
+```typescript
+type AssetVariantType =
+  | 'thumbnail'   // Small preview
+  | 'preview'     // Medium preview
+  | 'webp'        // WebP optimized
+  | 'mp4_low'     // Low-res video
+  | 'mp4_high'    // High-res video
+  | 'original';   // Original file
+```
+
+### AssetType
+
+```typescript
+type AssetType =
+  | 'image'       // Image files
+  | 'video'       // Video files
+  | 'audio'       // Audio files
+  | 'transition'  // Transition videos
+  | 'other';      // Other file types
+```
+
+---
+
+## Event Payloads
+
+```typescript
+interface PreloadStartEvent {
+  jobId: string;
+  assetId: string;
+  url: string;
+}
+
+interface PreloadProgressEvent {
+  jobId: string;
+  progress: number;      // 0-100
+  bytesLoaded: number;
+  totalBytes: number;
+}
+
+interface PreloadCompleteEvent {
+  jobId: string;
+  assetId: string;
+}
+
+interface PreloadErrorEvent {
+  jobId: string;
+  assetId: string;
+  error: string;
+}
+
+interface ProjectDownloadProgressEvent {
+  projectId: string;
+  progress: number;
+  downloadedAssets: number;
+  totalAssets: number;
+  downloadedBytes: number;
+  totalBytes: number;
+}
+
+interface ProjectDownloadCompleteEvent {
+  projectId: string;
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Use Optional Hook Outside Provider
+
+```typescript
+// Good - won't crash if outside provider
+const ctx = useDownloadContextOptional();
+if (ctx?.isDownloading) { ... }
+
+// Bad - will crash if outside provider
+const ctx = useDownloadContext();  // throws Error
+```
+
+### 2. Memoize Computed Values
+
+```typescript
+// Good - values memoized in context
+const { activeCount, totalProgress } = useDownloadContext();
+
+// Avoid recomputing in consumers
+const activeCount = useMemo(
+  () => jobs.filter(j => j.status === 'downloading').length,
+  [jobs]
+);  // Already computed by context
+```
+
+### 3. Use Appropriate State Source
+
+```typescript
+// For global UI (headers, status bars)
+const ctx = useDownloadContext();
+
+// For isolated components
+const progress = usePreloadProgress();
+```
+
+### 4. Clean Up Jobs
+
+```typescript
+// Clear completed jobs when user dismisses
+<button onClick={clearAllCompleted}>Clear completed</button>
+
+// Clear specific job
+<button onClick={() => clearJob(job.id)}>×</button>
+```
+
+---
+
+## File Inventory
+
+| File | LOC | Purpose |
+|------|-----|---------|
+| `DownloadContext.tsx` | 256 | Context provider and hooks |
+| `DownloadEventBus.ts` | 180 | Event emitter (related) |
+| `usePreloadProgress.ts` | 221 | Hook alternative (related) |
+| `offline.ts` (types) | 195 | Type definitions (related) |
+| `offline.config.ts` | 53 | Event names, storage config (related) |
+| `preload.config.ts` | 95 | Priority, auto-cleanup (related) |
+| **Core Context** | **256** | |
+| **With Related** | **1,000** | |
+
+---
+
+## Related Documentation
+
+- [hooks-module.md](./hooks-module.md) - usePreloadProgress, useOfflineMode, useStorageQuota
+- [lib-module.md](./lib-module.md) - DownloadEventBus, StorageManager
+- [config-module.md](./config-module.md) - OFFLINE_CONFIG, PRELOAD_CONFIG
+- [types-module.md](./types-module.md) - Offline types
+- [components-module.md](./components-module.md) - Offline components
+
+---
+
+## Adding New Contexts
+
+To add a new React Context:
+
+### Step 1: Create Context File
+
+```typescript
+// context/MyContext.tsx
+import React, { createContext, useContext, useState, type ReactNode } from 'react';
+
+interface MyContextValue {
+  value: string;
+  setValue: (v: string) => void;
+}
+
+const MyContext = createContext<MyContextValue | null>(null);
+
+export function MyProvider({ children }: { children: ReactNode }) {
+  const [value, setValue] = useState('');
+
+  return (
+    <MyContext.Provider value={{ value, setValue }}>
+      {children}
+    </MyContext.Provider>
+  );
+}
+
+export function useMyContext(): MyContextValue {
+  const ctx = useContext(MyContext);
+  if (!ctx) {
+    throw new Error('useMyContext must be used within MyProvider');
+  }
+  return ctx;
+}
+
+export function useMyContextOptional(): MyContextValue | null {
+  return useContext(MyContext);
+}
+```
+
+### Step 2: Add Provider to _app.tsx
+
+```typescript
+import { MyProvider } from '../context/MyContext';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <Provider store={store}>
+      <DownloadProvider>
+        <MyProvider>
+          {/* ... */}
+        </MyProvider>
+      </DownloadProvider>
+    </Provider>
+  );
+}
+```
+
+### Step 3: Consume in Components
+
+```typescript
+import { useMyContext } from '@/context/MyContext';
+
+function MyComponent() {
+  const { value, setValue } = useMyContext();
+  // ...
+}
+```
diff --git a/frontend/docs/factories-module.md b/frontend/docs/factories-module.md
new file mode 100644
index 0000000..edca23c
--- /dev/null
+++ b/frontend/docs/factories-module.md
@@ -0,0 +1,847 @@
+# Frontend Factories Module
+
+## Overview
+
+The Factories module provides **code generation patterns** that eliminate massive boilerplate across the frontend application. These factories generate complete components, pages, Redux slices, and table configurations from declarative configurations.
+
+**Location:** Multiple directories (factory pattern is distributed)
+
+**Total Lines:** ~1,291 LOC across 6 factory files
+
+---
+
+## Architecture
+
+```
+frontend/src/
+├── factories/                              # Page factories
+│   ├── createListPage.tsx      (193 LOC)  # List page generator
+│   ├── createFormPage.tsx      (331 LOC)  # Form page generator
+│   └── index.ts                (6 LOC)    # Exports
+├── components/
+│   ├── Factory/
+│   │   └── createTableComponent.tsx (118 LOC)  # Table component generator
+│   └── DataGrid/
+│       └── configBuilderFactory.tsx (301 LOC)  # Column config generator
+└── stores/
+    └── createEntitySlice.ts    (342 LOC)  # Redux slice generator
+```
+
+---
+
+## Factory Relationship Diagram
+
+```
+                    ┌────────────────────────────────────┐
+                    │         createListPage             │
+                    │    (generates list pages)          │
+                    └────────────────┬───────────────────┘
+                                     │ uses
+                                     ▼
+                    ┌────────────────────────────────────┐
+                    │       createTableComponent         │
+                    │    (generates table wrappers)      │
+                    └────────────────┬───────────────────┘
+                                     │ wraps
+                                     ▼
+                    ┌────────────────────────────────────┐
+                    │         GenericTable               │
+                    │    (reusable data grid)            │
+                    └────────────────┬───────────────────┘
+                                     │ uses
+                    ┌────────────────┴───────────────────┐
+                    ▼                                    ▼
+┌───────────────────────────────┐    ┌────────────────────────────────┐
+│     createColumnLoader        │    │      createEntitySlice         │
+│   (column config generator)   │    │    (Redux slice generator)     │
+└───────────────────────────────┘    └────────────────────────────────┘
+```
+
+---
+
+## Factory Files
+
+### 1. createListPage (`factories/createListPage.tsx`)
+
+**Purpose:** Generate complete list pages with filtering, CSV import/export, and permissions.
+
+**Lines:** 193 LOC
+
+#### Configuration Interface
+
+```typescript
+interface ListPageConfig {
+  entityName: string;              // URL path segment (e.g., 'roles')
+  entityTitle: string;             // Page title (e.g., 'Roles')
+  TableComponent: React.ComponentType<{
+    filterItems: FilterItem[];
+    setFilterItems: (items: FilterItem[]) => void;
+    filters: Filter[];
+    showGrid?: boolean;
+  }>;
+  filters: Filter[];               // Available filter fields
+  readPermission: string;          // Permission to view (e.g., 'READ_ROLES')
+  createPermission: string;        // Permission to create (e.g., 'CREATE_ROLES')
+  uploadCsvAction: AsyncThunk<unknown, File, object>;  // Redux thunk for CSV upload
+  setRefetchAction: (value: boolean) => { type: string; payload: boolean };  // Action to trigger data refresh
+  newItemLabel?: string;           // Custom "New Item" button text
+  cardBoxId?: string;              // Optional card container ID
+}
+```
+
+#### Generated Features
+
+| Feature | Description |
+|---------|-------------|
+| Page Title | HTML `<title>` via Next.js Head |
+| Permission Guard | `LayoutAuthenticated` wrapper with `readPermission` |
+| New Item Button | Links to `-new` page (if `createPermission`) |
+| Filter Button | Adds dynamic filter rows |
+| Download CSV | Exports entity data as CSV |
+| Upload CSV | Modal with drag-drop file picker |
+| Table Display | Renders configured `TableComponent` |
+
+#### Usage Example
+
+```typescript
+// pages/roles/roles-list.tsx
+import { createListPage } from '../../factories/createListPage';
+import TableRoles from '../../components/Roles/TableRoles';
+import { uploadCsv, setRefetch } from '../../stores/roles/rolesSlice';
+
+const filters = [
+  { label: 'Name', title: 'name' },
+  { label: 'Permissions', title: 'permissions' },
+];
+
+export default createListPage({
+  entityName: 'roles',
+  entityTitle: 'Roles',
+  TableComponent: TableRoles,
+  filters,
+  readPermission: 'READ_ROLES',
+  createPermission: 'CREATE_ROLES',
+  uploadCsvAction: uploadCsv,
+  setRefetchAction: setRefetch,
+});
+```
+
+**Result:** 24 lines of code generates a complete list page (~200 lines equivalent).
+
+---
+
+### 2. createFormPage (`factories/createFormPage.tsx`)
+
+**Purpose:** Generate form pages for creating and editing entities with Formik integration.
+
+**Lines:** 331 LOC
+
+#### Field Types
+
+```typescript
+type FormFieldType =
+  | 'text'           // Text input
+  | 'email'          // Email input with validation
+  | 'number'         // Numeric input
+  | 'textarea'       // Multi-line text
+  | 'select'         // Single-select relation
+  | 'selectMany'     // Multi-select relation
+  | 'enumSelect'     // Select from predefined options
+  | 'switch'         // Boolean toggle
+  | 'image'          // Image picker
+  | 'date'           // Date picker
+  | 'datetime'       // DateTime picker
+  | 'password'       // Password input
+  | 'custom';        // Custom component
+```
+
+#### Field Configuration
+
+```typescript
+interface FormFieldConfig {
+  name: string;           // Form field name
+  label: string;          // Display label
+  type: FormFieldType;    // Field type
+  placeholder?: string;   // Input placeholder
+  itemRef?: string;       // Entity reference for select fields
+  showField?: string;     // Display field for relations
+  options?: Array<{       // Options for enumSelect
+    value: string;
+    label: string;
+  }>;
+  path?: string;          // Upload path for images
+  schema?: {              // Image constraints
+    size?: number;
+    formats?: string[];
+  };
+  component?: React.ComponentType;  // Custom component
+  props?: Record<string, unknown>;  // Custom component props
+}
+```
+
+#### Page Configuration
+
+```typescript
+interface FormPageConfig<T> {
+  entityName: string;         // Entity URL segment
+  entityTitle: string;        // Page title
+  singularTitle: string;      // Singular form (e.g., 'Role')
+  mode: 'create' | 'edit';    // Form mode
+  sliceSelector: Selector;    // Redux state selector
+  fetchAction?: AsyncThunk;   // Fetch for edit mode
+  createAction?: AsyncThunk;  // Create thunk
+  updateAction?: AsyncThunk;  // Update thunk
+  permission: string;         // Required permission
+  initialValues: T;           // Default form values
+  fields: FormFieldConfig[];  // Field definitions
+  validate?: Validator;       // Formik validation
+}
+```
+
+#### Usage Example
+
+```typescript
+// pages/users/users-new.tsx
+import { createFormPage } from '../../factories/createFormPage';
+import { create } from '../../stores/users/usersSlice';
+
+export default createFormPage({
+  entityName: 'users',
+  entityTitle: 'Users',
+  singularTitle: 'User',
+  mode: 'create',
+  sliceSelector: (state) => state.users,
+  createAction: create,
+  permission: 'CREATE_USERS',
+  initialValues: {
+    firstName: '',
+    lastName: '',
+    email: '',
+    role: null,
+  },
+  fields: [
+    { name: 'firstName', label: 'First Name', type: 'text' },
+    { name: 'lastName', label: 'Last Name', type: 'text' },
+    { name: 'email', label: 'Email', type: 'email' },
+    { name: 'role', label: 'Role', type: 'select', itemRef: 'roles', showField: 'name' },
+  ],
+});
+```
+
+#### Field Rendering Logic
+
+The `renderField` helper function handles all field types:
+
+```typescript
+function renderField(field: FormFieldConfig, formValues: T): React.ReactNode {
+  switch (field.type) {
+    case 'text':
+    case 'email':
+    case 'password':
+      return <Field name={name} type={type} placeholder={placeholder} />;
+
+    case 'select':
+      return <Field name={name} component={SelectField} options={...} />;
+
+    case 'switch':
+      return <Field name={name} component={SwitchField} />;
+
+    case 'image':
+      return <Field name={name} component={FormImagePicker} path={path} />;
+
+    case 'custom':
+      return <Field name={name} component={CustomComponent} {...props} />;
+
+    // ... other types
+  }
+}
+```
+
+---
+
+### 3. createTableComponent (`components/Factory/createTableComponent.tsx`)
+
+**Purpose:** Generate table wrapper components that connect GenericTable with entity-specific configuration.
+
+**Lines:** 118 LOC
+
+#### Entity Slice State Interface
+
+```typescript
+interface EntitySliceState<T> {
+  [key: string]: T[] | boolean | number | NotificationState | unknown[];
+  loading: boolean;
+  count: number;
+  refetch: boolean;
+  notify: NotificationState;
+}
+```
+
+#### Configuration Interface
+
+```typescript
+interface TableComponentConfig<T extends BaseEntity> {
+  entityName: string;                     // Entity identifier
+  sliceSelector: (state: RootState) => EntitySliceState<T>;  // Redux slice selector
+  fetchAction: AsyncThunk<
+    T | { rows: T[]; count: number },
+    { id?: string; query?: string },
+    object
+  >;
+  updateAction: AsyncThunk<T, { id: string; data: Partial<T> }, object>;
+  deleteAction: AsyncThunk<void, string, object>;
+  deleteByIdsAction: AsyncThunk<void, string[], object>;
+  setRefetchAction: (refetch: boolean) => { type: string; payload: boolean };
+  loadColumnsFunction: (
+    onDelete: (id: string) => void,
+    entityName: string,
+    user: unknown,
+  ) => Promise<GridColDef[]>;
+}
+```
+
+#### Generated Props Interface
+
+```typescript
+interface TableComponentProps {
+  filterItems: FilterItem[];
+  setFilterItems: (items: FilterItem[]) => void;
+  filters: Filter[];
+  showGrid?: boolean;
+}
+```
+
+#### Usage Example
+
+```typescript
+// components/Roles/TableRoles.tsx
+import { createTableComponent } from '../Factory/createTableComponent';
+import { fetch, update, deleteItem, setRefetch, deleteItemsByIds } from '../../stores/roles/rolesSlice';
+import { loadColumns } from './configureRolesCols';
+import type { Role } from '../../types/entities';
+
+const TableRoles = createTableComponent<Role>({
+  entityName: 'roles',
+  sliceSelector: (state) => state.roles,
+  fetchAction: fetch,
+  updateAction: update,
+  deleteAction: deleteItem,
+  deleteByIdsAction: deleteItemsByIds,
+  setRefetchAction: setRefetch,
+  loadColumnsFunction: loadColumns,
+});
+
+export default TableRoles;
+```
+
+**Result:** 13 lines replaces ~100 lines of boilerplate.
+
+---
+
+### 4. configBuilderFactory (`components/DataGrid/configBuilderFactory.tsx`)
+
+**Purpose:** Generate MUI X DataGrid column configurations from declarative metadata.
+
+**Lines:** 301 LOC
+
+#### Default Column Properties
+
+```typescript
+const DEFAULT_COLUMN_PROPS = {
+  flex: 1,
+  minWidth: 120,
+  filterable: false,
+  headerClassName: 'datagrid--header',
+  cellClassName: 'datagrid--cell',
+};
+```
+
+#### Column Metadata Interface
+
+```typescript
+interface ColumnMetadata {
+  field: string;              // Data field name
+  headerName: string;         // Column header
+  type?:                      // Column type
+    | 'text'
+    | 'boolean'
+    | 'date'
+    | 'datetime'
+    | 'number'
+    | 'relation'
+    | 'relationMany'
+    | 'singleSelectRelation'
+    | 'image'
+    | 'actions';
+  editable?: boolean;         // Allow inline editing
+  sortable?: boolean;         // Allow sorting
+  width?: number;             // Fixed width
+  flex?: number;              // Flex grow
+  minWidth?: number;          // Minimum width
+  entityRef?: string;         // Related entity for relations
+  displayField?: string;      // Field to display for relations
+  renderCell?: (params: GridRenderCellParams) => React.ReactElement;  // Custom cell renderer
+  valueFormatter?: (value: unknown) => string;  // Value transformation
+}
+```
+
+#### Column Builder Configuration
+
+```typescript
+interface ColumnBuilderConfig {
+  entityName: string;         // Entity identifier
+  entityPath?: string;        // URL path (defaults to entityName)
+  columns: ColumnMetadata[];  // Column definitions
+  updatePermission?: string;  // Override update permission check
+}
+```
+
+#### Key Functions
+
+| Function | Purpose |
+|----------|---------|
+| `buildColumns()` | Async function that builds complete column array |
+| `createColumnLoader()` | Factory that returns column loader function |
+| `fetchRelationOptions()` | Fetches options for singleSelectRelation columns |
+| `buildColumn()` | Builds individual column definition |
+| `buildActionsColumn()` | Builds actions column with edit/view/delete |
+| `getFormatter()` | Returns appropriate value formatter |
+
+#### Column Type Handling
+
+```typescript
+// Type-specific column configuration
+switch (col.type) {
+  case 'boolean':
+    baseColumn.type = 'boolean';
+    baseColumn.valueFormatter = ({ value }) => dataFormatter.booleanFormatter(value);
+    break;
+
+  case 'datetime':
+    baseColumn.type = 'dateTime';
+    baseColumn.valueGetter = (_value, row) => new Date(row[col.field]);
+    break;
+
+  case 'relation':
+  case 'relationMany':
+    baseColumn.type = 'singleSelect';
+    baseColumn.renderEditCell = (params) => (
+      <DataGridMultiSelect {...params} entityName={col.entityRef} />
+    );
+    break;
+
+  case 'image':
+    baseColumn.renderCell = (params) => (
+      <span style={{ backgroundImage: `url(${params.value[0]?.publicUrl})` }} />
+    );
+    break;
+}
+```
+
+#### Usage Example
+
+```typescript
+// components/Roles/configureRolesCols.tsx
+import { createColumnLoader, ColumnMetadata } from '../DataGrid/configBuilderFactory';
+
+const ROLES_COLUMNS: ColumnMetadata[] = [
+  { field: 'name', headerName: 'Name', type: 'text', editable: true },
+  { field: 'permissions', headerName: 'Permissions', type: 'relationMany', entityRef: 'permissions' },
+  { field: 'actions', headerName: '', type: 'actions' },
+];
+
+export const loadColumns = createColumnLoader({
+  entityName: 'roles',
+  columns: ROLES_COLUMNS,
+});
+```
+
+**Result:** 12 lines replaces ~150 lines of column configuration.
+
+---
+
+### 5. createEntitySlice (`stores/createEntitySlice.ts`)
+
+**Purpose:** Generate complete Redux Toolkit slices with CRUD async thunks.
+
+**Lines:** 342 LOC
+
+#### Imported Types
+
+The factory imports types from dedicated type files:
+
+```typescript
+import type {
+  EntitySliceConfig,
+  NotificationState,
+  EntitySliceState,
+} from '../types/redux';
+import type { PaginatedResponse, FetchParams, ApiError } from '../types/api';
+import type { BaseEntity } from '../types/entities';
+```
+
+#### Configuration Interface
+
+```typescript
+interface EntitySliceConfig {
+  name: string;          // Slice name (e.g., 'roles')
+  endpoint: string;      // API endpoint (e.g., 'roles')
+  singularName?: string; // Singular form for notifications (e.g., 'Role')
+}
+```
+
+#### Generated Actions
+
+| Action | Type | Description |
+|--------|------|-------------|
+| `fetch` | AsyncThunk | Fetch single item by ID or paginated list |
+| `create` | AsyncThunk | Create new entity |
+| `update` | AsyncThunk | Update existing entity |
+| `deleteItem` | AsyncThunk | Delete single item |
+| `deleteItemsByIds` | AsyncThunk | Bulk delete items |
+| `uploadCsv` | AsyncThunk | Import entities from CSV |
+| `setRefetch` | Action | Trigger data refresh |
+
+#### Generated State
+
+```typescript
+interface InternalSliceState<T> {
+  [entityName]: T[];     // Entity array
+  loading: boolean;      // Loading state
+  count: number;         // Total count for pagination
+  refetch: boolean;      // Refetch trigger flag
+  rolesWidgets: unknown[]; // Legacy widgets support
+  notify: NotificationState; // Notification state
+}
+```
+
+#### Notification Handling
+
+Each async action automatically handles notifications:
+
+```typescript
+// Fulfilled state
+builder.addCase(create.fulfilled, (state) => {
+  state.loading = false;
+  fulfilledNotify(state, `${displayName} has been created`);
+});
+
+// Rejected state
+builder.addCase(create.rejected, (state, action) => {
+  state.loading = false;
+  rejectNotify(state, action);
+});
+```
+
+#### Usage Example
+
+```typescript
+// stores/roles/rolesSlice.ts
+import { createEntitySlice } from '../createEntitySlice';
+import type { Role } from '../../types/entities';
+
+const { slice, actions, reducer: baseReducer } = createEntitySlice<Role>({
+  name: 'roles',
+  endpoint: 'roles',
+  singularName: 'Role',
+});
+
+// Export standard CRUD actions
+export const { fetch, create, update, deleteItem, deleteItemsByIds, uploadCsv, setRefetch } = actions;
+export const rolesSlice = slice;
+export default baseReducer;
+```
+
+**Result:** 10 lines generates complete Redux slice (~300 lines equivalent).
+
+#### Exported Type
+
+The factory exports a utility type for accessing actions:
+
+```typescript
+export type EntityActions<T extends BaseEntity> = ReturnType<
+  typeof createEntitySlice<T>
+>['actions'];
+```
+
+#### Helper Functions
+
+The factory includes internal helper functions:
+
+| Function | Purpose |
+|----------|---------|
+| `isPaginatedResponse<T>()` | Type guard to check if response has `rows` and `count` |
+| `isAxiosError()` | Type guard for Axios errors |
+| `getSingularName()` | Get singular form for notifications |
+| `capitalize()` | Capitalize first letter of string |
+
+#### Custom Thunks Extension
+
+Slices can add custom thunks alongside generated ones when an existing legacy
+entity flow still requires Redux-side server calls. New server-state flows
+should use TanStack Query instead of adding new entity CRUD thunks.
+
+---
+
+## GenericTable Component
+
+The `GenericTable` component (`components/Generic/GenericTable.tsx`, 429 LOC) is the foundation that table factories wrap.
+
+### Features
+
+| Feature | Implementation |
+|---------|----------------|
+| Server-side pagination | `paginationMode='server'` |
+| Server-side sorting | `sortingMode='server'` |
+| Row selection | Checkbox selection with bulk actions |
+| Inline editing | Row edit mode with validation |
+| Dynamic filters | Formik-based filter panel |
+| Notifications | Toast notifications via react-toastify |
+| Permissions | Column editability based on user permissions |
+
+### Props Interface
+
+```typescript
+interface GenericTableProps<T extends BaseEntity> {
+  entityName: string;
+  sliceSelector: StateSelector<T>;
+  fetchAction: AsyncThunk;
+  updateAction: AsyncThunk;
+  deleteAction: AsyncThunk;
+  deleteByIdsAction?: AsyncThunk;
+  setRefetchAction: ActionCreator;
+  loadColumnsFunction: ColumnLoader;
+  filters: Filter[];
+  filterItems: FilterItem[];
+  setFilterItems: Setter;
+  extraQuery?: string;
+}
+```
+
+---
+
+## Entity Implementation Pattern
+
+Complete pattern for adding a new entity using all factories:
+
+### Step 1: Create Entity Slice
+
+```typescript
+// stores/widgets/widgetsSlice.ts
+import { createEntitySlice } from '../createEntitySlice';
+import type { Widget } from '../../types/entities';
+
+const { slice, actions, reducer } = createEntitySlice<Widget>({
+  name: 'widgets',
+  endpoint: 'widgets',
+  singularName: 'Widget',
+});
+
+export const { fetch, create, update, deleteItem, deleteItemsByIds, uploadCsv, setRefetch } = actions;
+export default reducer;
+```
+
+### Step 2: Create Column Configuration
+
+```typescript
+// components/Widgets/configureWidgetsCols.tsx
+import { createColumnLoader, ColumnMetadata } from '../DataGrid/configBuilderFactory';
+
+const WIDGETS_COLUMNS: ColumnMetadata[] = [
+  { field: 'name', headerName: 'Name', type: 'text', editable: true },
+  { field: 'status', headerName: 'Status', type: 'text' },
+  { field: 'createdAt', headerName: 'Created', type: 'datetime' },
+  { field: 'actions', headerName: '', type: 'actions' },
+];
+
+export const loadColumns = createColumnLoader({
+  entityName: 'widgets',
+  columns: WIDGETS_COLUMNS,
+});
+```
+
+### Step 3: Create Table Component
+
+```typescript
+// components/Widgets/TableWidgets.tsx
+import { createTableComponent } from '../Factory/createTableComponent';
+import { fetch, update, deleteItem, setRefetch, deleteItemsByIds } from '../../stores/widgets/widgetsSlice';
+import { loadColumns } from './configureWidgetsCols';
+import type { Widget } from '../../types/entities';
+
+const TableWidgets = createTableComponent<Widget>({
+  entityName: 'widgets',
+  sliceSelector: (state) => state.widgets,
+  fetchAction: fetch,
+  updateAction: update,
+  deleteAction: deleteItem,
+  deleteByIdsAction: deleteItemsByIds,
+  setRefetchAction: setRefetch,
+  loadColumnsFunction: loadColumns,
+});
+
+export default TableWidgets;
+```
+
+### Step 4: Create List Page
+
+```typescript
+// pages/widgets/widgets-list.tsx
+import { createListPage } from '../../factories/createListPage';
+import TableWidgets from '../../components/Widgets/TableWidgets';
+import { uploadCsv, setRefetch } from '../../stores/widgets/widgetsSlice';
+
+const filters = [
+  { label: 'Name', title: 'name' },
+  { label: 'Status', title: 'status' },
+];
+
+export default createListPage({
+  entityName: 'widgets',
+  entityTitle: 'Widgets',
+  TableComponent: TableWidgets,
+  filters,
+  readPermission: 'READ_WIDGETS',
+  createPermission: 'CREATE_WIDGETS',
+  uploadCsvAction: uploadCsv,
+  setRefetchAction: setRefetch,
+});
+```
+
+### Step 5: Create Form Pages
+
+```typescript
+// pages/widgets/widgets-new.tsx
+import { createFormPage } from '../../factories/createFormPage';
+import { create } from '../../stores/widgets/widgetsSlice';
+
+export default createFormPage({
+  entityName: 'widgets',
+  entityTitle: 'Widgets',
+  singularTitle: 'Widget',
+  mode: 'create',
+  sliceSelector: (state) => state.widgets,
+  createAction: create,
+  permission: 'CREATE_WIDGETS',
+  initialValues: { name: '', status: 'draft' },
+  fields: [
+    { name: 'name', label: 'Name', type: 'text' },
+    { name: 'status', label: 'Status', type: 'enumSelect', options: [
+      { value: 'draft', label: 'Draft' },
+      { value: 'active', label: 'Active' },
+    ]},
+  ],
+});
+```
+
+**Total:** ~80 lines for complete CRUD implementation (~1,500 lines equivalent without factories).
+
+---
+
+## Boilerplate Reduction
+
+| Component | Without Factory | With Factory | Reduction |
+|-----------|-----------------|--------------|-----------|
+| Redux Slice | ~300 LOC | ~10 LOC | **97%** |
+| List Page | ~200 LOC | ~24 LOC | **88%** |
+| Form Page | ~250 LOC | ~30 LOC | **88%** |
+| Table Component | ~100 LOC | ~13 LOC | **87%** |
+| Column Config | ~150 LOC | ~12 LOC | **92%** |
+| **Total per Entity** | **~1,000 LOC** | **~89 LOC** | **91%** |
+
+With 13 entities in the application, factories eliminate approximately **11,843 lines** of boilerplate code.
+
+---
+
+## Type Safety
+
+All factories are fully typed with TypeScript generics:
+
+```typescript
+// createEntitySlice with type parameter
+const { actions } = createEntitySlice<Role>({ ... });
+// actions.fetch: AsyncThunk<Role | PaginatedResponse<Role>, FetchParams, ...>
+
+// createTableComponent with type parameter
+const TableRoles = createTableComponent<Role>({ ... });
+// TableRoles: React.FC<TableComponentProps>
+
+// createFormPage with type parameter
+const RolesNew = createFormPage<RoleFormValues>({ ... });
+// Type-safe form values throughout
+```
+
+---
+
+## Best Practices
+
+### 1. Use Consistent Naming
+
+```typescript
+// Entity name should match across all layers
+const entityName = 'widgets';  // Used in:
+// - Slice: stores/widgets/widgetsSlice.ts
+// - Table: components/Widgets/TableWidgets.tsx
+// - Pages: pages/widgets/widgets-list.tsx
+```
+
+### 2. Permission Naming Convention
+
+```typescript
+// Permissions follow pattern: ACTION_ENTITY
+readPermission: 'READ_WIDGETS',
+createPermission: 'CREATE_WIDGETS',
+updatePermission: 'UPDATE_WIDGETS',  // Used by configBuilderFactory
+deletePermission: 'DELETE_WIDGETS',
+```
+
+### 3. Type Definitions
+
+```typescript
+// Always define entity type in types/entities.ts
+export interface Widget extends BaseEntity {
+  name: string;
+  status: 'draft' | 'active';
+}
+
+// Use type parameter in all factories
+createEntitySlice<Widget>({ ... });
+createTableComponent<Widget>({ ... });
+```
+
+### 4. Custom Extensions
+
+```typescript
+// Add custom thunks after factory generation
+const { slice, actions, reducer } = createEntitySlice<Widget>({ ... });
+
+// Custom widget-specific thunk
+export const archiveWidget = createAsyncThunk(
+  'widgets/archive',
+  async (id: string) => { ... }
+);
+```
+
+---
+
+## Related Documentation
+
+- [stores-module.md](./stores-module.md) - Redux state management
+- [components-module.md](./components-module.md) - Component organization
+- [pages-module.md](./pages-module.md) - Page structure
+- [types-module.md](./types-module.md) - TypeScript types
+- [hooks-module.md](./hooks-module.md) - Custom hooks
+
+---
+
+## File Inventory
+
+| File | Location | LOC | Purpose |
+|------|----------|-----|---------|
+| `createListPage.tsx` | `factories/` | 193 | List page generator |
+| `createFormPage.tsx` | `factories/` | 331 | Form page generator |
+| `index.ts` | `factories/` | 6 | Exports |
+| `createTableComponent.tsx` | `components/Factory/` | 118 | Table wrapper generator |
+| `configBuilderFactory.tsx` | `components/DataGrid/` | 301 | Column config generator |
+| `createEntitySlice.ts` | `stores/` | 342 | Redux slice generator |
+| **Total** | | **1,291** | |
diff --git a/frontend/docs/frontend-architecture.md b/frontend/docs/frontend-architecture.md
new file mode 100644
index 0000000..687301d
--- /dev/null
+++ b/frontend/docs/frontend-architecture.md
@@ -0,0 +1,1238 @@
+# Frontend Architecture
+
+## Overview
+
+The frontend is a **Next.js 15** application with **React 19**, **TypeScript**, **Redux Toolkit**, and **Tailwind CSS**. It uses the Pages Router with client-side rendering (CSR), optimized for complex admin/builder interactions and PWA offline capabilities.
+
+**Location:** `frontend/src/`
+
+**Total Files:** 408 TypeScript/TSX files across 14 directories
+
+---
+
+## Tech Stack
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Next.js | 15.3.1 | React framework with Pages Router |
+| React | 19.0.0 | UI library |
+| TypeScript | 5.x | Type safety |
+| Redux Toolkit | 2.1.0 | State management |
+| MUI X DataGrid | 7.0.0 | Data tables |
+| Tailwind CSS | 3.4.1 | Utility-first styling |
+| Formik | 2.4.x | Form management |
+| Axios | 1.x | HTTP client |
+| Serwist | 9.x | PWA service worker |
+| Dexie.js | 4.x | IndexedDB wrapper |
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           ENTRY LAYER                                        │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ pages/_app.tsx                                                          │ │
+│  │   • Redux Provider (store.ts)                                           │ │
+│  │   • DownloadContext (PWA progress)                                      │ │
+│  │   • Axios interceptors (JWT refresh, error handling)                    │ │
+│  │   • PWA service worker registration (Serwist)                           │ │
+│  │   • ErrorBoundary wrapper                                               │ │
+│  │   • i18n initialization                                                 │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           LAYOUT LAYER                                       │
+│  ┌───────────────────────────────────┐  ┌─────────────────────────────────┐ │
+│  │ Authenticated.tsx                 │  │ Guest.tsx                       │ │
+│  │   • JWT validation (client-side)  │  │   • Public routes only          │ │
+│  │   • Permission checking per route │  │   • Login, Register, Forgot     │ │
+│  │   • Project existence guard       │  │   • Minimal layout              │ │
+│  │   • NavBar, AsideMenu, FooterBar  │  │                                 │ │
+│  │   • Tour guide (IntroGuide)       │  │                                 │ │
+│  └───────────────────────────────────┘  └─────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           PAGE LAYER (99 pages)                              │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ Entity CRUD Pages (78 pages = 13 entities × 6 pages each)               │ │
+│  │   • [entity]-list.tsx   → createListPage factory                        │ │
+│  │   • [entity]-new.tsx    → Formik forms with validation                  │ │
+│  │   • [entity]-edit.tsx   → useEditPageSync hook                          │ │
+│  │   • [entity]-view.tsx   → Read-only display                             │ │
+│  │   • [entity]-table.tsx  → Embedded table view                           │ │
+│  │   • [entityId].tsx      → Dynamic route handler                         │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ Special Pages (21 pages)                                                │ │
+│  │   • constructor.tsx     → Visual tour builder (47KB)                    │ │
+│  │   • dashboard.tsx       → Admin home with entity counts                 │ │
+│  │   • p/[slug]/index.tsx  → Public production presentation                │ │
+│  │   • p/[slug]/stage.tsx  → Stage preview presentation                    │ │
+│  │   • login.tsx, forgot.tsx, password-reset.tsx → Auth flows              │ │
+│  │   • profile.tsx         → User profile management                       │ │
+│  │   • element-type-defaults.tsx → Global element defaults                 │ │
+│  │   • project-element-defaults.tsx → Project element overrides            │ │
+│  │   • search.tsx          → Global search                                 │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        COMPONENT LAYER (193 components)                      │
+│  ┌────────────────────────┐  ┌────────────────────────┐  ┌────────────────┐ │
+│  │ Entity Components (78) │  │ Constructor (15)       │  │ Runtime (5)    │ │
+│  │  • Table[Entity]       │  │  • ElementEditorPanel  │  │  • Runtime-    │ │
+│  │  • configure*Cols      │  │  • CanvasElement       │  │    Presentation│ │
+│  │  • Card[Entity]        │  │  • CanvasBackground    │  │  • Runtime-    │ │
+│  │  • List[Entity]        │  │  • ConstructorMenu     │  │    Element     │ │
+│  │  • Form fields         │  │  • PageSelector        │  │  • UiElement-  │ │
+│  └────────────────────────┘  │  • TransitionPreview   │  │    Renderer    │ │
+│  ┌────────────────────────┐  └────────────────────────┘  │                │ │
+│  │ ElementSettings (23)   │  ┌────────────────────────┐  └────────────────┘ │
+│  │  • StyleSettings       │  │ Offline/PWA (5)        │  ┌────────────────┐ │
+│  │  • NavigationSettings  │  │  • DownloadProgress    │  │ Generic (50+)  │ │
+│  │  • EffectsSettings     │  │  • OfflineToggle       │  │  • CardBox*    │ │
+│  │  • CarouselSettings    │  │  • StorageUsage        │  │  • FormField*  │ │
+│  │  • MediaSettings       │  │  • OfflineStatus       │  │  • NavBar*     │ │
+│  │  • TooltipSettings     │  └────────────────────────┘  │  • AsideMenu*  │ │
+│  └────────────────────────┘                              │  • BaseButton  │ │
+│  ┌────────────────────────┐                              │  • Pagination  │ │
+│  │ Factories (2)          │                              │  • Search      │ │
+│  │  • createTableComp     │                              └────────────────┘ │
+│  │  • configBuilderFact   │                                               │
+│  └────────────────────────┘                                               │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           HOOKS LAYER (32 hooks)                             │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ Runtime/Preloading (8 hooks)                                            │ │
+│  │   usePreloadOrchestrator ──→ usePageSwitch ──→ useBackgroundTransition  │ │
+│  │          │                         │                                    │ │
+│  │          ▼                         ▼                                    │ │
+│  │   useNeighborGraph          useTransitionPlayback ──→ useReversePlayback│ │
+│  │          │                                                              │ │
+│  │          ▼                                                              │ │
+│  │   usePageDataLoader ──→ usePreloadProgress                              │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ Constructor (7 hooks)                                                   │ │
+│  │   useConstructorElements ──→ useConstructorPageActions                  │ │
+│  │          │                                                              │ │
+│  │          ▼                                                              │ │
+│  │   useCanvasElementDrag ──→ useCanvasElapsedTime                         │ │
+│  │          │                                                              │ │
+│  │          ▼                                                              │ │
+│  │   useTransitionPreview ──→ useIconPreload ──→ useMediaDurationProbe     │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│  ┌────────────────────────┐  ┌────────────────────────┐  ┌────────────────┐ │
+│  │ Offline/PWA (4)        │  │ Forms/Tables (4)       │  │ Utility (8)    │ │
+│  │  • useOfflineMode      │  │  • useFormSync         │  │  • useCSV-     │ │
+│  │  • usePWAPreload       │  │  • useEntityTable      │  │    Handling    │ │
+│  │  • useStorageQuota     │  │  • useFilterItems      │  │  • useElement- │ │
+│  │  • useNetworkAware     │  │  • useEditPageSync     │  │    Effects     │ │
+│  └────────────────────────┘  └────────────────────────┘  │  • useOutside- │ │
+│                                                          │    Click       │ │
+│                                                          │  • useDraggable│ │
+│                                                          └────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           STATE LAYER                                        │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ Redux Store (stores/store.ts)                                           │ │
+│  │  ┌─────────────────────────────────────────────────────────────────┐    │ │
+│  │  │ Entity Slices (13) - via createEntitySlice factory              │    │ │
+│  │  │   users, roles, permissions, projects, project_memberships,     │    │ │
+│  │  │   assets, asset_variants, presigned_url_requests, tour_pages,   │    │ │
+│  │  │   project_audio_tracks, publish_events, pwa_caches, access_logs │    │ │
+│  │  └─────────────────────────────────────────────────────────────────┘    │ │
+│  │  ┌─────────────────────────────────────────────────────────────────┐    │ │
+│  │  │ Core Slices (3)                                                 │    │ │
+│  │  │   • authSlice    - JWT token, current user, permissions         │    │ │
+│  │  │   • mainSlice    - UI state (sidebar, dark mode)                │    │ │
+│  │  │   • styleSlice   - Theme configuration                          │    │ │
+│  │  └─────────────────────────────────────────────────────────────────┘    │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ React Context                                                           │ │
+│  │   • DownloadContext - PWA download progress tracking                    │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           LIBRARY LAYER (20 files)                           │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ lib/offline/ - PWA Storage                                              │ │
+│  │   • StorageManager.ts   - Cache API + IndexedDB dual storage            │ │
+│  │   • DownloadManager.ts  - Asset download orchestration                  │ │
+│  │   • DownloadEventBus.ts - Progress event system (Observer pattern)      │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ lib/offlineDb/ - IndexedDB Persistence                                  │ │
+│  │   • OfflineDbManager.ts - Dexie.js wrapper for large assets             │ │
+│  │   • schema.ts           - Database schema definition                    │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+│  ┌─────────────────────────────────────────────────────────────────────────┐ │
+│  │ lib/ - Utilities                                                        │ │
+│  │   • assetUrl.ts         - Presigned URL management, expiry handling     │ │
+│  │   • elementDefaults.ts  - Default element configurations (17KB)         │ │
+│  │   • elementStyles.ts    - Element CSS generation                        │ │
+│  │   • elementEffects.ts   - Element animation effects                     │ │
+│  │   • constructorHelpers.ts - Canvas manipulation utilities               │ │
+│  │   • navigationHelpers.ts - Link resolution, transition detection        │ │
+│  │   • extractPageLinks.ts - Parse navigation links from ui_schema         │ │
+│  │   • imagePreDecode.ts   - Image pre-decoding for smooth transitions     │ │
+│  │   • mediaDuration.ts    - Audio/video duration extraction               │ │
+│  │   • mediaHelpers.ts     - Media URL handling                            │ │
+│  │   • parseJson.ts        - Safe JSON parsing with fallbacks              │ │
+│  │   • logger.ts           - Structured logging (dev/prod modes)           │ │
+│  │   • slugHelpers.ts      - URL slug generation                           │ │
+│  │   • tourFlowHelpers.ts  - Page ordering utilities                       │ │
+│  └─────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           SUPPORT LAYER                                      │
+│  ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────────┐ │
+│  │ factories/ (3)     │  │ schemas/ (6)       │  │ types/ (12)            │ │
+│  │  • createListPage  │  │  • userSchema      │  │  • constructor.ts      │ │
+│  │  • createFormPage  │  │  • assetSchema     │  │  • entities.ts         │ │
+│  │  • index           │  │  • projectSchema   │  │  • runtime.ts          │ │
+│  └────────────────────┘  │  • tourPageSchema  │  │  • preload.ts          │ │
+│  ┌────────────────────┐  │  • roleSchema      │  │  • presentation.ts     │ │
+│  │ helpers/ (6)       │  └────────────────────┘  │  • offline.ts          │ │
+│  │  • dataFormatter   │  ┌────────────────────┐  │  • permissions.ts      │ │
+│  │  • textFormatters  │  │ config/ (2)        │  │  • forms.ts            │ │
+│  │  • userPermissions │  │  • preload.config  │  │  • filters.ts          │ │
+│  │  • notifyState     │  │  • offline.config  │  │  • api.ts              │ │
+│  │  • humanize        │  └────────────────────┘  │  • redux.ts            │ │
+│  │  • fileSaver       │                          └────────────────────────┘ │
+│  └────────────────────┘                                                      │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Directory Structure
+
+```
+frontend/src/
+├── pages/                    # 99 files - Next.js pages
+│   ├── _app.tsx              # App entry point
+│   ├── api/                  # API routes (logError.ts, hello.js)
+│   ├── p/[projectSlug]/      # Public presentation routes
+│   │   ├── index.tsx         # Production presentation
+│   │   └── stage.tsx         # Stage preview
+│   ├── constructor.tsx       # Visual tour builder
+│   ├── dashboard.tsx         # Admin home
+│   ├── [entity]/             # 13 entity directories
+│   │   ├── [entityId].tsx    # Dynamic route
+│   │   ├── [entity]-list.tsx # List page
+│   │   ├── [entity]-new.tsx  # Create page
+│   │   ├── [entity]-edit.tsx # Edit page
+│   │   ├── [entity]-view.tsx # View page
+│   │   └── [entity]-table.tsx# Embedded table
+│   └── ...                   # Auth, profile, search, etc.
+│
+├── components/               # 193 files - React components
+│   ├── [Entity]/             # 13 entity component directories
+│   │   ├── Table[Entity].tsx # DataGrid wrapper
+│   │   ├── configure[Entity]Cols.tsx # Column config
+│   │   ├── Card[Entity].tsx  # Card view
+│   │   └── List[Entity].tsx  # List view
+│   ├── Constructor/          # 15 files - Tour builder components
+│   ├── ElementSettings/      # 23 files - Element configuration
+│   ├── UiElements/           # 16 files - Unified element rendering (shared by Constructor + Runtime)
+│   ├── Offline/              # 5 files - PWA components
+│   ├── Generic/              # 3 files - Reusable table/form
+│   ├── DataGrid/             # 1 file - Column config factory
+│   ├── Factory/              # 1 file - Table component factory
+│   ├── Uploaders/            # 1 file - Upload service
+│   └── *.tsx                 # ~50 standalone components
+│
+├── hooks/                    # 32 files - Custom React hooks
+│   ├── index.ts              # Re-exports
+│   ├── usePreloadOrchestrator.ts  # Asset preloading (26KB)
+│   ├── useTransitionPlayback.ts   # Video transitions (23KB)
+│   ├── usePageSwitch.ts           # Page navigation (14KB)
+│   ├── useConstructorElements.ts  # Element CRUD (12KB)
+│   └── ...                        # 26 more hooks
+│
+├── stores/                   # Redux state
+│   ├── store.ts              # Store configuration
+│   ├── hooks.ts              # useAppSelector, useAppDispatch
+│   ├── createEntitySlice.ts  # Entity slice factory (10KB)
+│   ├── authSlice.ts          # Authentication state
+│   ├── mainSlice.ts          # UI state
+│   ├── styleSlice.ts         # Theme state
+│   └── [entity]/             # 13 entity slice directories
+│       └── [entity]Slice.ts  # Generated via factory
+│
+├── lib/                      # 20 files - Utility libraries
+│   ├── offline/              # PWA storage layer
+│   │   ├── StorageManager.ts # Cache API + IndexedDB
+│   │   ├── DownloadManager.ts# Download orchestration
+│   │   └── DownloadEventBus.ts # Progress events
+│   ├── offlineDb/            # IndexedDB layer
+│   │   ├── OfflineDbManager.ts # Dexie wrapper
+│   │   └── schema.ts         # DB schema
+│   ├── assetUrl.ts           # Presigned URL management
+│   ├── elementDefaults.ts    # Default element configs
+│   ├── elementStyles.ts      # CSS generation
+│   ├── elementEffects.ts     # Animation effects
+│   ├── constructorHelpers.ts # Canvas utilities
+│   ├── navigationHelpers.ts  # Link resolution
+│   ├── extractPageLinks.ts   # Parse links from schema
+│   ├── imagePreDecode.ts     # Image pre-decoding
+│   ├── mediaDuration.ts      # Media duration extraction
+│   ├── mediaHelpers.ts       # Media URL handling
+│   ├── parseJson.ts          # Safe JSON parsing
+│   ├── logger.ts             # Structured logging
+│   ├── slugHelpers.ts        # Slug generation
+│   └── tourFlowHelpers.ts    # Page ordering
+│
+├── types/                    # 12 files - TypeScript definitions
+│   ├── constructor.ts        # Canvas/element types
+│   ├── entities.ts           # Entity interfaces
+│   ├── runtime.ts            # Presentation runtime
+│   ├── preload.ts            # Preloading state
+│   ├── presentation.ts       # Navigation/transitions
+│   ├── offline.ts            # PWA/cache types
+│   ├── permissions.ts        # RBAC types
+│   ├── forms.ts              # Form field types
+│   ├── filters.ts            # Data filtering
+│   ├── api.ts                # API response types
+│   ├── redux.ts              # Store types
+│   └── index.ts              # Re-exports
+│
+├── factories/                # 3 files - Page generators
+│   ├── createListPage.tsx    # List page factory
+│   ├── createFormPage.tsx    # Form page factory
+│   └── index.ts              # Re-exports
+│
+├── schemas/                  # 6 files - Validation schemas
+│   ├── userSchema.ts         # User validation
+│   ├── assetSchema.ts        # Asset validation
+│   ├── projectSchema.ts      # Project validation
+│   ├── tourPageSchema.ts     # Tour page validation
+│   ├── roleSchema.ts         # Role validation
+│   └── index.ts              # Re-exports
+│
+├── helpers/                  # 6 files - Utility functions
+│   ├── dataFormatter.js      # Data formatting
+│   ├── textFormatters.ts     # Text formatting
+│   ├── userPermissions.ts    # Permission checking
+│   ├── notifyStateHandler.ts # Toast notifications
+│   ├── humanize.ts           # Human-readable strings
+│   └── fileSaver.ts          # File download
+│
+├── layouts/                  # 2 files - Page layouts
+│   ├── Authenticated.tsx     # Auth layout with nav
+│   └── Guest.tsx             # Public layout
+│
+├── config/                   # 2 files - Configuration
+│   ├── preload.config.ts     # Preload settings
+│   └── offline.config.ts     # PWA settings
+│
+├── context/                  # 1 file - React Context
+│   └── DownloadContext.tsx   # PWA download progress
+│
+├── interfaces/               # 1 file - Shared interfaces
+│   └── index.ts              # Common UI interfaces
+│
+└── css/                      # Stylesheets
+    └── _theme.css            # Tailwind theme customization
+```
+
+---
+
+## Module Details
+
+### 1. Pages Module (99 files)
+
+#### Entity CRUD Pages (78 files)
+Each of the 13 entities has 6 standardized pages:
+
+| Page Pattern | Purpose | Factory/Hook |
+|--------------|---------|--------------|
+| `[entity]-list.tsx` | List with filters, pagination, CSV export | `createListPage` factory |
+| `[entity]-new.tsx` | Create form with validation | Formik + entity schema |
+| `[entity]-edit.tsx` | Edit form with data sync | `useEditPageSync` hook |
+| `[entity]-view.tsx` | Read-only display | Direct entity fetch |
+| `[entity]-table.tsx` | Embedded table view | `createTableComponent` |
+| `[entityId].tsx` | Dynamic route redirect | Redirects to -view |
+
+**Entities:** users, roles, permissions, projects, project_memberships, assets, asset_variants, presigned_url_requests, tour_pages, project_audio_tracks, publish_events, pwa_caches, access_logs
+
+#### Special Pages (21 files)
+
+| Page | Size | Description |
+|------|------|-------------|
+| `index.tsx` | 1KB | Root redirect to login or projects list |
+| `constructor.tsx` | 47KB | Visual tour builder with canvas, drag-drop, element editing |
+| `dashboard.tsx` | 6KB | Admin home with entity counts, quick actions |
+| `p/[projectSlug]/index.tsx` | 2KB | Public production presentation (wraps RuntimePresentation) |
+| `p/[projectSlug]/stage.tsx` | 2KB | Stage preview presentation |
+| `_app.tsx` | 11KB | App entry, providers, interceptors |
+| `login.tsx` | 8KB | Authentication with OAuth options |
+| `forgot.tsx` | 3KB | Password reset request |
+| `profile.tsx` | 6KB | User profile management |
+| `element-type-defaults.tsx` | 4KB | Global element defaults editor |
+| `project-element-defaults.tsx` | 6KB | Project-level element overrides |
+| `search.tsx` | 3KB | Global search results |
+
+---
+
+### 2. Components Module (193 files)
+
+#### Entity Components (78 files, 13 directories)
+
+Each entity directory contains:
+
+| File Pattern | Purpose |
+|--------------|---------|
+| `Table[Entity].tsx` | MUI DataGrid wrapper with actions |
+| `configure[Entity]Cols.tsx` | Column definitions using configBuilderFactory |
+| `Card[Entity].tsx` | Card view for single entity |
+| `List[Entity].tsx` | List view variant |
+| `useAssetUploader.ts` | (Assets only) Upload hook |
+| `ProjectSelector.tsx` | (Assets only) Project filter |
+
+#### Constructor Components (15 files)
+
+| Component | Size | Description |
+|-----------|------|-------------|
+| `ElementEditorPanel.tsx` | 22KB | Right panel for element editing |
+| `ConstructorToolbar.tsx` | ~19KB | Floating main toolbar with mode, Page actions, Elements actions, save/stage/exit controls |
+| `ConstructorMenu.tsx` | 5KB | Legacy/collapsible constructor menu component |
+| `ConstructorControlsPanel.tsx` | 2KB | Legacy/secondary constructor controls |
+| `CanvasElement.tsx` | 3KB | Draggable element on canvas |
+| `CanvasBackground.tsx` | 3KB | Background image/video layer |
+| `CreateTransitionForm.tsx` | 3KB | Transition configuration modal |
+| `TransitionPreviewOverlay.tsx` | 1KB | Transition video preview |
+| `PageSelector.tsx` | 1KB | Page dropdown selector |
+| `InteractionModeToggle.tsx` | 2KB | Edit/interact mode toggle |
+| `AssetSelectCompact.tsx` | 2KB | Compact asset picker |
+| `BackgroundSettingsEditor.tsx` | 2KB | Background configuration |
+| `ElementEditorHeader.tsx` | 1KB | Editor panel header |
+| `MenuActionButton.tsx` | 1KB | Menu button component |
+| `types.ts` | 7KB | Constructor type definitions |
+| `index.ts` | 0.3KB | Re-exports |
+
+#### ElementSettings Components (23 files)
+
+Settings panels for different element aspects:
+
+| Component | Description |
+|-----------|-------------|
+| `StyleSettingsSection.tsx` | Position, size, colors, borders |
+| `StyleSettingsSectionCompact.tsx` | Compact version for constructor |
+| `NavigationSettingsSection.tsx` | Link targets, transitions |
+| `NavigationSettingsSectionCompact.tsx` | Compact version |
+| `EffectsSettingsSection.tsx` | Animations, hover effects |
+| `EffectsSettingsSectionCompact.tsx` | Compact version |
+| `CarouselSettingsSection.tsx` | Gallery/carousel configuration |
+| `GallerySettingsSection.tsx` | Image gallery settings |
+| `MediaSettingsSection.tsx` | Video/audio player settings |
+| `MediaSettingsSectionCompact.tsx` | Compact version |
+| `TooltipSettingsSection.tsx` | Tooltip configuration |
+| `TooltipSettingsSectionCompact.tsx` | Compact version |
+| `DescriptionSettingsSection.tsx` | Text content settings |
+| `DescriptionSettingsSectionCompact.tsx` | Compact version |
+| `CommonSettingsSection.tsx` | Shared element settings |
+| `CommonSettingsSectionCompact.tsx` | Compact version |
+| `GallerySettingsSection.tsx` | Gallery settings |
+| `GallerySettingsSectionCompact.tsx` | Compact version |
+| `GalleryCarouselSettingsSectionCompact.tsx` | Gallery carousel settings |
+| `ElementSettingsTabs.tsx` | Tab navigation |
+| `useElementSettingsForm.ts` | Form state management hook |
+| `types.ts` | Type definitions |
+| `index.ts` | Re-exports |
+
+#### UiElements Components (16 files)
+
+Unified element rendering shared by both Constructor (CanvasElement) and Runtime (RuntimeElement):
+
+| Component | Description |
+|-----------|-------------|
+| `UiElementRenderer.tsx` | Main entry point - delegates to per-type components |
+| `shared/useElementWrapperStyle.ts` | Shared hook for consistent wrapper styling |
+| `elements/NavigationElement.tsx` | Navigation button (next/prev) |
+| `elements/GalleryElement.tsx` | Image gallery grid |
+| `elements/TooltipElement.tsx` | Tooltip with icon |
+| `elements/DescriptionElement.tsx` | Title + text block |
+| `elements/CarouselElement.tsx` | Image carousel with navigation |
+| `elements/LogoElement.tsx` | Logo display |
+| `elements/SpotElement.tsx` | Hotspot/clickable area |
+| `elements/VideoPlayerElement.tsx` | Embedded video player |
+| `elements/AudioPlayerElement.tsx` | Embedded audio player |
+| `elements/PopupElement.tsx` | Popup/modal dialog |
+| `GalleryCarouselOverlay.tsx` | Gallery/carousel fullscreen overlay |
+| `ElementPreview.tsx` | Preview element in constructor |
+| `defaults.ts` | Default element configurations |
+| `types.ts` | Element type definitions |
+
+#### Offline Components (5 files)
+
+| Component | Description |
+|-----------|-------------|
+| `DownloadProgressPanel.tsx` | Shows download progress for PWA |
+| `OfflineToggle.tsx` | Enable/disable offline mode |
+| `StorageUsageDisplay.tsx` | Shows storage quota usage |
+| `OfflineStatusIndicator.tsx` | Online/offline status badge |
+| `index.ts` | Re-exports |
+
+#### Factory Components (2 files)
+
+| Component | Description |
+|-----------|-------------|
+| `createTableComponent.tsx` | Factory that generates table wrapper components |
+| `configBuilderFactory.tsx` | Factory that generates DataGrid column configurations |
+
+#### Generic Components (3 files)
+
+| Component | Size | Description |
+|-----------|------|-------------|
+| `GenericTable.tsx` | 14KB | Reusable DataGrid with filters, pagination |
+| `GenericFormField.tsx` | 6KB | Reusable form field component |
+| `index.ts` | 0.2KB | Re-exports |
+
+#### Standalone Components (~50 files)
+
+| Category | Components |
+|----------|------------|
+| **Layout** | `NavBar`, `NavBarItem`, `FooterBar`, `AsideMenu`, `AsideMenuItem`, `AsideMenuLayer`, `AsideMenuList` |
+| **Cards** | `CardBox`, `CardBoxModal`, `CardBoxComponentBody`, `CardBoxComponentTitle`, `CardBoxComponentFooter`, `CardBoxComponentEmpty` |
+| **Forms** | `FormField`, `FormFieldCompact`, `FormFilePicker`, `FormImagePicker`, `FormCheckRadio`, `FormCheckRadioGroup` |
+| **Buttons** | `BaseButton`, `BaseButtons`, `BaseIcon`, `BaseDivider` |
+| **Data** | `DataGridMultiSelect`, `SelectField`, `SelectFieldMany`, `SwitchField`, `RichTextField`, `ImageField` |
+| **Sections** | `SectionMain`, `SectionFullScreen`, `SectionTitle`, `SectionTitleLineWithButton` |
+| **User** | `UserAvatar`, `UserAvatarCurrentUser`, `UserCard`, `IconRounded` |
+| **Utils** | `Pagination`, `Search`, `SearchResults`, `LoadingSpinner`, `NotificationBar`, `OverlayLayer`, `ClickOutside` |
+| **Auth** | `PasswordSetOrReset` |
+| **Features** | `TourFlowManager`, `RuntimePresentation`, `RuntimeElement`, `DevModeBadge`, `IntroGuide`, `LanguageSwitcher`, `ErrorBoundary`, `DragDropFilePicker`, `ListActionsPopover` |
+
+---
+
+### 3. Hooks Module (32 files)
+
+#### Runtime/Preloading Hooks (8 hooks)
+
+| Hook | Size | Description | Used By |
+|------|------|-------------|---------|
+| `usePreloadOrchestrator` | 26KB | Coordinates asset preloading with priority queue, blob URL caching | RuntimePresentation |
+| `useTransitionPlayback` | 23KB | Manages video transition playback (forward/reverse) | RuntimePresentation |
+| `usePageSwitch` | 14KB | Handles page navigation with preloaded assets | RuntimePresentation |
+| `useReversePlayback` | 11KB | Reverse video playback for back navigation | useTransitionPlayback |
+| `useNeighborGraph` | 8KB | Builds navigation graph for preload prioritization | usePreloadOrchestrator |
+| `usePageDataLoader` | 7KB | Loads project and pages data with caching | RuntimePresentation |
+| `usePreloadProgress` | 6KB | Tracks preload progress percentages | RuntimePresentation |
+| `useBackgroundTransition` | 5KB | Fade-out animation during page transitions | RuntimePresentation |
+
+#### Constructor Hooks (7 hooks)
+
+| Hook | Size | Description | Used By |
+|------|------|-------------|---------|
+| `useConstructorElements` | 12KB | Element CRUD operations on canvas | constructor.tsx |
+| `useConstructorPageActions` | 10KB | Page management (create, delete, reorder) | constructor.tsx |
+| `useMediaDurationProbe` | 6KB | Extracts duration from video/audio files | constructor.tsx |
+| `useTransitionPreview` | 6KB | Previews transition videos | constructor.tsx |
+| `useDraggable` | 6KB | Generic drag functionality | CanvasElement |
+| `useIconPreload` | 5KB | Preloads icon assets | constructor.tsx |
+| `useCanvasElementDrag` | 4KB | Canvas-specific element dragging | CanvasElement |
+| `useCanvasElapsedTime` | 3KB | Animation timing for canvas | constructor.tsx |
+
+#### Offline/PWA Hooks (4 hooks)
+
+| Hook | Size | Description | Used By |
+|------|------|-------------|---------|
+| `useOfflineMode` | 11KB | Detects and manages offline state | _app.tsx, Offline components |
+| `usePWAPreload` | 5KB | Preloads assets for PWA mode | RuntimePresentation |
+| `useNetworkAware` | 5KB | Network quality detection | usePreloadOrchestrator |
+| `useStorageQuota` | 3KB | Monitors storage usage | StorageUsageDisplay |
+
+#### Form/Table Hooks (4 hooks)
+
+| Hook | Size | Description | Used By |
+|------|------|-------------|---------|
+| `useEntityTable` | 8KB | Table state management (pagination, sorting, filters) | All entity tables |
+| `useEditPageSync` | 5KB | Syncs form data with Redux on edit pages | All -edit pages |
+| `useFilterItems` | 5KB | Filter state management | createListPage |
+| `useFormSync` | 3KB | Form state synchronization | Form components |
+
+#### Utility Hooks (8 hooks)
+
+| Hook | Size | Description | Used By |
+|------|------|-------------|---------|
+| `useDashboardCounts` | 8KB | Fetches entity counts for dashboard | dashboard.tsx |
+| `useElementEffects` | 3KB | Applies element animation effects | RuntimeElement |
+| `useCSVHandling` | 4KB | CSV import/export | List pages |
+| `useOutsideClick` | 3KB | Detects clicks outside element | Modals, dropdowns |
+| `usePageNavigation` | 5KB | Page navigation state | RuntimePresentation |
+| `useProjectAssets` | 3KB | Fetches and manages project assets | Projects pages |
+| `useDevCompilationStatus` | 1KB | Hot reload status indicator | DevModeBadge |
+
+---
+
+### 4. Stores Module (22 files)
+
+#### Store Configuration
+
+| File | Description |
+|------|-------------|
+| `store.ts` | Redux store configuration with all slices |
+| `hooks.ts` | Typed hooks: `useAppSelector`, `useAppDispatch` |
+| `createEntitySlice.ts` | Factory for generating entity slices |
+| `introSteps.ts` | Tour guide step definitions |
+
+#### Core Slices
+
+| Slice | Size | State |
+|-------|------|-------|
+| `authSlice.ts` | 4KB | `{ token, currentUser, permissions, loading, error }` |
+| `mainSlice.ts` | 1KB | `{ isAsideMobileExpanded, isAsideLgActive, darkMode }` |
+| `styleSlice.ts` | 3KB | `{ asideStyle, navBarStyle, footerStyle, ... }` |
+| `usersSlice.ts` | 3KB | Extended user slice with password reset actions |
+
+#### Entity Slices (13)
+
+Generated via `createEntitySlice` factory, each provides:
+
+```typescript
+interface EntityState<T> {
+  rows: T[];
+  row: T | null;
+  loading: boolean;
+  error: string | null;
+  count: number;
+  filters: FilterState;
+}
+
+// Async thunks
+fetch({ query: string })     // GET /api/[entity]?...
+findById(id: string)         // GET /api/[entity]/:id
+create(data: T)              // POST /api/[entity]
+update({ id, data })         // PUT /api/[entity]/:id
+deleteItem(id: string)       // DELETE /api/[entity]/:id
+```
+
+---
+
+### 5. Library Module (20 files)
+
+#### Offline Storage (lib/offline/)
+
+| File | Size | Description |
+|------|------|-------------|
+| `StorageManager.ts` | 7KB | Dual storage abstraction (Cache API < 5MB, IndexedDB >= 5MB) |
+| `DownloadManager.ts` | 12KB | Download orchestration with retry, progress |
+| `DownloadEventBus.ts` | 5KB | Event system for download progress (Observer pattern) |
+
+#### IndexedDB (lib/offlineDb/)
+
+| File | Size | Description |
+|------|------|-------------|
+| `OfflineDbManager.ts` | 8KB | Dexie.js wrapper for large asset storage |
+| `schema.ts` | 1KB | IndexedDB schema: `assets { url, blob, size, timestamp }` |
+
+#### Element Utilities
+
+| File | Size | Description |
+|------|------|-------------|
+| `elementDefaults.ts` | 18KB | Default configurations for all 11 element types |
+| `elementStyles.ts` | 3KB | Generates inline CSS from element config |
+| `elementEffects.ts` | 6KB | Animation effect definitions and application |
+| `fonts.ts` | 2KB | Font family definitions and mappings |
+
+#### Asset Utilities
+
+| File | Size | Description |
+|------|------|-------------|
+| `assetUrl.ts` | 10KB | Presigned URL management, expiry tracking, refresh |
+| `imagePreDecode.ts` | 6KB | Pre-decodes images for smooth transitions |
+| `mediaDuration.ts` | 3KB | Extracts duration from video/audio elements |
+| `mediaHelpers.ts` | 4KB | Media URL normalization, type detection |
+
+#### Navigation Utilities
+
+| File | Size | Description |
+|------|------|-------------|
+| `navigationHelpers.ts` | 4KB | `resolveNavigationTarget()`, `isTransitionBlocking()` |
+| `extractPageLinks.ts` | 6KB | Parses navigation links from `ui_schema_json` |
+
+#### Constructor Utilities
+
+| File | Size | Description |
+|------|------|-------------|
+| `constructorHelpers.ts` | 8KB | Canvas manipulation, element positioning |
+| `slugHelpers.ts` | 2KB | URL slug generation for pages |
+| `tourFlowHelpers.ts` | 3KB | Page ordering, drag-drop reordering |
+
+#### General Utilities
+
+| File | Size | Description |
+|------|------|-------------|
+| `parseJson.ts` | 3KB | Safe JSON parsing with fallbacks |
+| `logger.ts` | 4KB | Structured logging (console in dev, silent in prod) |
+
+---
+
+### 6. Types Module (12 files)
+
+| File | Size | Description |
+|------|------|-------------|
+| `constructor.ts` | 10KB | Canvas element, page, selection types |
+| `entities.ts` | 7KB | All 13 entity interfaces |
+| `runtime.ts` | 2KB | Runtime presentation state types |
+| `preload.ts` | 1KB | Preload queue, progress types |
+| `presentation.ts` | 2KB | Navigation, transition types |
+| `offline.ts` | 4KB | PWA cache, download types |
+| `permissions.ts` | 4KB | RBAC permission types |
+| `forms.ts` | 2KB | Form field, validation types |
+| `filters.ts` | 2KB | Data filter types |
+| `api.ts` | 1KB | API response types |
+| `redux.ts` | 1KB | Store, dispatch types |
+| `index.ts` | 0.3KB | Re-exports |
+
+---
+
+### 7. Factories Module (3 files)
+
+| Factory | Size | Description |
+|---------|------|-------------|
+| `createListPage.tsx` | 6KB | Generates list pages with filters, CSV, pagination |
+| `createFormPage.tsx` | 9KB | Generates form pages with validation |
+| `index.ts` | 0.1KB | Re-exports |
+
+**createListPage Usage:**
+```typescript
+export default createListPage({
+  entityName: 'assets',
+  entityNamePlural: 'Assets',
+  permissionPrefix: 'ASSETS',
+  columns: configureAssetsCols,
+  filterFields: ['name', 'type', 'status'],
+});
+```
+
+**createFormPage Usage:**
+```typescript
+export default createFormPage({
+  entityName: 'assets',
+  schema: assetSchema,
+  fields: ['name', 'file', 'project'],
+});
+```
+
+---
+
+### 8. Schemas Module (6 files)
+
+Formik/Yup validation schemas:
+
+| Schema | Fields Validated |
+|--------|-----------------|
+| `userSchema.ts` | email, firstName, lastName, password, role |
+| `assetSchema.ts` | name, file, type, project |
+| `projectSchema.ts` | name, slug, description |
+| `tourPageSchema.ts` | name, slug, order, background |
+| `roleSchema.ts` | name, permissions |
+| `index.ts` | Re-exports |
+
+---
+
+### 9. Helpers Module (6 files)
+
+| Helper | Description |
+|--------|-------------|
+| `dataFormatter.js` | Format dates, numbers, booleans for display |
+| `textFormatters.ts` | Truncate, capitalize, slugify text |
+| `userPermissions.ts` | `hasPermission()`, `canAccess()` utilities |
+| `notifyStateHandler.ts` | Toast notification triggers |
+| `humanize.ts` | Convert snake_case to readable text |
+| `fileSaver.ts` | Trigger file downloads |
+
+---
+
+### 10. Layouts Module (2 files)
+
+| Layout | Description |
+|--------|-------------|
+| `Authenticated.tsx` | Full layout with JWT validation, permission checks, NavBar, AsideMenu, FooterBar, IntroGuide |
+| `Guest.tsx` | Minimal layout for public pages (login, password reset, public presentations) |
+
+**Per-Page Layout Pattern:**
+```typescript
+UsersListPage.getLayout = (page: ReactElement) => (
+  <LayoutAuthenticated permission="READ_USERS">
+    {page}
+  </LayoutAuthenticated>
+);
+```
+
+---
+
+### 11. Config Module (2 files)
+
+| Config | Settings |
+|--------|----------|
+| `preload.config.ts` | Priority weights, batch sizes, concurrent limits |
+| `offline.config.ts` | Cache names, storage thresholds, expiry times |
+
+**Preload Priority Weights:**
+```typescript
+export const PRELOAD_PRIORITY = {
+  TRANSITION_VIDEO: 150,  // Highest - needed for navigation
+  IMAGE: 100,
+  AUDIO: 50,
+  VIDEO: 30,              // Lowest - large files
+};
+```
+
+---
+
+### 12. Context Module (1 file)
+
+| Context | Description |
+|---------|-------------|
+| `DownloadContext.tsx` | PWA download progress tracking, shared across components |
+
+**Usage:**
+```typescript
+const { progress, isDownloading, startDownload, cancelDownload } = useDownloadContext();
+```
+
+---
+
+## Design Patterns
+
+### 1. Factory Pattern
+
+**Eliminates ~80% boilerplate code:**
+
+| Factory | Generates | Files Eliminated |
+|---------|-----------|-----------------|
+| `createEntitySlice` | Redux slices with CRUD thunks | 13 × 200 LOC = 2600 LOC |
+| `createListPage` | List pages with filters, pagination | 13 × 150 LOC = 1950 LOC |
+| `createFormPage` | Form pages with validation | 13 × 180 LOC = 2340 LOC |
+| `createTableComponent` | Table wrapper components | 13 × 50 LOC = 650 LOC |
+| `configBuilderFactory` | Column configurations | 13 × 80 LOC = 1040 LOC |
+
+**Total: ~8500 LOC eliminated through factories**
+
+### 2. Custom Hook Pattern
+
+Hooks are composed hierarchically:
+
+```
+usePreloadOrchestrator
+    ├── useNeighborGraph (build priority queue)
+    ├── useNetworkAware (adjust batch size)
+    └── Internal: presigned URL fetching, blob caching
+
+usePageSwitch
+    ├── usePreloadOrchestrator.getReadyBlobUrl()
+    └── useBackgroundTransition (fade animation)
+
+useTransitionPlayback
+    ├── useReversePlayback (back navigation)
+    └── Internal: video element management
+```
+
+### 3. HOC via getLayout
+
+Per-page layout injection without wrapper components:
+
+```typescript
+// Page defines its layout
+MyPage.getLayout = (page) => (
+  <LayoutAuthenticated permission="READ_ASSETS">
+    {page}
+  </LayoutAuthenticated>
+);
+
+// _app.tsx applies it
+const getLayout = Component.getLayout ?? ((page) => page);
+return getLayout(<Component {...pageProps} />);
+```
+
+### 4. Repository Pattern
+
+Entity slices abstract all API calls:
+
+```typescript
+// Component only knows about Redux actions
+dispatch(fetch({ query: '?limit=100' }));
+dispatch(create(newAsset));
+dispatch(update({ id, data: changes }));
+dispatch(deleteItem(id));
+
+// Slice handles API communication
+const fetch = createAsyncThunk('assets/fetch', async ({ query }) => {
+  const response = await axios.get(`/api/assets${query}`);
+  return response.data;
+});
+```
+
+### 5. Observer Pattern
+
+Download progress events:
+
+```typescript
+// DownloadEventBus.ts
+class DownloadEventBus {
+  private listeners: Map<string, Set<Callback>>;
+
+  emit(event: 'progress' | 'complete' | 'error', data: any) {
+    this.listeners.get(event)?.forEach(cb => cb(data));
+  }
+
+  on(event: string, callback: Callback) {
+    this.listeners.get(event)?.add(callback);
+  }
+}
+
+// Consumer
+downloadEventBus.on('progress', ({ url, percent }) => {
+  setProgress(prev => ({ ...prev, [url]: percent }));
+});
+```
+
+### 6. Strategy Pattern
+
+Storage selection based on file size:
+
+```typescript
+// StorageManager.ts
+class StorageManager {
+  async store(url: string, blob: Blob) {
+    if (blob.size < 5 * 1024 * 1024) {  // < 5MB
+      return this.cacheApiStore(url, blob);  // Fast, limited
+    } else {
+      return this.indexedDbStore(url, blob); // Slow, unlimited
+    }
+  }
+}
+```
+
+---
+
+## Key Flows
+
+### 1. Runtime Presentation Flow
+
+```
+User navigates to /p/[slug]
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ usePageDataLoader                   │
+│   • Fetch project by slug           │
+│   • Fetch pages for environment     │
+│   • Determine initial page          │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ usePreloadOrchestrator              │
+│   • Build neighbor graph            │
+│   • Calculate priorities            │
+│   • Request presigned URLs          │
+│   • Download assets to cache        │
+│   • Pre-decode images               │
+│   • Store blob URLs                 │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ RuntimePresentation renders         │
+│   • Background (image/video)        │
+│   • RuntimeElement for each element │
+│     └── UiElementRenderer           │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ User clicks navigation element      │
+│   • resolveNavigationTarget()       │
+│   • isTransitionBlocking()          │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ usePageSwitch                       │
+│   • Get blob URL from cache (O(1))  │
+│   • useBackgroundTransition()       │
+│   • If transition video:            │
+│     useTransitionPlayback()         │
+│   • Switch to new page              │
+└─────────────────────────────────────┘
+```
+
+### 2. Constructor Flow
+
+```
+User opens /constructor?projectId=X
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ Fetch project and pages             │
+│   • Redux: projects.findById()      │
+│   • Redux: tour_pages.fetch()       │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ useConstructorElements              │
+│   • Parse ui_schema_json            │
+│   • Initialize element state        │
+│   • Provide CRUD methods            │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ Canvas renders                      │
+│   • CanvasBackground                │
+│   • CanvasElement for each element  │
+│   • useCanvasElementDrag            │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ User edits element                  │
+│   • ElementEditorPanel opens        │
+│   • useElementSettingsForm          │
+│   • Settings sections render        │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ Save changes                        │
+│   • Update ui_schema_json           │
+│   • Redux: tour_pages.update()      │
+│   • API: PUT /api/tour_pages/:id    │
+└─────────────────────────────────────┘
+```
+
+### 3. Offline/PWA Flow
+
+```
+User enables offline mode
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ DownloadManager.startDownload()     │
+│   • Get asset manifest              │
+│   • Request presigned URLs          │
+│   • Queue downloads                 │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ For each asset:                     │
+│   • Fetch with progress tracking    │
+│   • DownloadEventBus.emit()         │
+│   • StorageManager.store()          │
+│     - Cache API (< 5MB)             │
+│     - IndexedDB (>= 5MB)            │
+└─────────────────────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────┐
+│ Service worker intercepts           │
+│   • Check Cache API                 │
+│   • Check IndexedDB                 │
+│   • Return cached response          │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Entity Architecture
+
+Each entity follows a consistent structure:
+
+```
+[Entity] (e.g., Assets)
+│
+├── pages/assets/
+│   ├── [assetsId].tsx          # Dynamic route → view
+│   ├── assets-list.tsx         # List with filters
+│   ├── assets-new.tsx          # Create form
+│   ├── assets-edit.tsx         # Edit form
+│   ├── assets-view.tsx         # Read-only view
+│   └── assets-table.tsx        # Embedded table
+│
+├── components/Assets/
+│   ├── TableAssets.tsx         # DataGrid wrapper
+│   ├── configureAssetsCols.tsx # Column definitions
+│   ├── CardAssets.tsx          # Card view
+│   ├── ListAssets.tsx          # List view
+│   ├── useAssetUploader.ts     # Upload hook (assets only)
+│   └── ProjectSelector.tsx     # Filter component
+│
+├── stores/assets/
+│   └── assetsSlice.ts          # Redux slice via factory
+│
+└── schemas/
+    └── assetSchema.ts          # Validation schema
+```
+
+**13 Entities:**
+- users, roles, permissions
+- projects, project_memberships
+- assets, asset_variants, presigned_url_requests
+- tour_pages, project_audio_tracks
+- publish_events, pwa_caches, access_logs
+
+---
+
+## Configuration
+
+### Next.js Config (`next.config.mjs`)
+
+```javascript
+const nextConfig = {
+  reactStrictMode: true,
+
+  typescript: {
+    ignoreBuildErrors: false,  // Enforce type checking
+  },
+
+  eslint: {
+    ignoreDuringBuilds: false, // Enforce linting
+  },
+
+  images: {
+    domains: ['cdn.platform.com', 's3.amazonaws.com'],
+  },
+
+  // PWA via Serwist
+  // Turbopack enabled for dev
+};
+```
+
+### Tailwind Config
+
+Theme customization in `css/_theme.css`:
+
+```css
+/* Sidebar styling */
+#asideMenu {
+  @apply bg-gray-900 text-white;
+}
+
+/* Theme variants */
+.theme-pink .card {
+  @apply border-pink-500;
+}
+```
+
+---
+
+## Performance Optimizations
+
+### 1. Asset Preloading
+
+- **Priority Queue:** Transition videos > Images > Audio > Video
+- **Batch Fetching:** Max 50 presigned URLs per request
+- **Network Awareness:** Reduce batch size on slow connections
+- **Blob URL Caching:** O(1) lookup during navigation
+
+### 2. Image Pre-Decoding
+
+```typescript
+// imagePreDecode.ts
+export async function preDecodeImage(blobUrl: string): Promise<void> {
+  const img = new Image();
+  img.src = blobUrl;
+  await img.decode();  // Decode before display
+}
+```
+
+### 3. Lazy Loading
+
+- Route-based code splitting (Next.js automatic)
+- Dynamic imports for large components
+
+### 4. Redux Optimization
+
+- Normalized entity state
+- Selective re-renders via `useAppSelector`
+- Memoized selectors where needed
+
+---
+
+## Related Documentation
+
+| Document | Description |
+|----------|-------------|
+| [hooks-reference.md](./hooks-reference.md) | Detailed hook documentation |
+| [runtime-presentation.md](./runtime-presentation.md) | Runtime presentation architecture |
+| [constructor-page-editor.md](./constructor-page-editor.md) | Constructor page documentation |
+| [assets-preloading.md](../../documentation/assets-preloading.md) | Asset preloading strategy |
+| [offline-pwa-mode.md](../../documentation/offline-pwa-mode.md) | PWA offline capabilities |
+| [ui-elements.md](../../documentation/ui-elements.md) | UI element types and configuration |
+
+---
+
+## File Reference by Size
+
+### Largest Files (> 10KB)
+
+| File | Size | Description |
+|------|------|-------------|
+| `pages/constructor.tsx` | 47KB | Visual tour builder |
+| `hooks/usePreloadOrchestrator.ts` | 26KB | Asset preloading |
+| `hooks/useTransitionPlayback.ts` | 23KB | Video transitions |
+| `components/Constructor/ElementEditorPanel.tsx` | 22KB | Element editor |
+| `components/RuntimePresentation.tsx` | 19KB | Tour playback |
+| `lib/elementDefaults.ts` | 18KB | Element defaults |
+| `components/TourFlowManager.tsx` | 17KB | Page management |
+| `hooks/usePageSwitch.ts` | 14KB | Page navigation |
+| `components/Generic/GenericTable.tsx` | 14KB | Reusable table |
+| `hooks/useConstructorElements.ts` | 12KB | Element CRUD |
+| `lib/offline/DownloadManager.ts` | 12KB | Download management |
+| `hooks/useReversePlayback.ts` | 11KB | Reverse video |
+| `hooks/useOfflineMode.ts` | 11KB | Offline detection |
+| `pages/_app.tsx` | 11KB | App entry |
+| `lib/assetUrl.ts` | 10KB | Presigned URLs |
+| `stores/createEntitySlice.ts` | 10KB | Slice factory |
+| `types/constructor.ts` | 10KB | Constructor types |
+
+---
+
+## Summary
+
+The frontend architecture demonstrates several strong patterns:
+
+**Strengths:**
+- Factory patterns eliminate ~8500 LOC of boilerplate
+- 32 custom hooks provide clean separation of concerns
+- Dual storage strategy (Cache API + IndexedDB) enables robust offline
+- Per-page layout pattern with permission checking
+- Strong TypeScript typing across 12 type definition files
+
+**Architecture Decisions:**
+- CSR-only approach (appropriate for admin/builder app)
+- Pages Router (stable, full-featured)
+- Redux Toolkit for predictable state management
+- MUI X DataGrid for complex data tables
+- Tailwind CSS for utility-first styling
+
+**Total Codebase:**
+- 408 TypeScript/TSX files
+- ~80,000 LOC estimated
+- 14 distinct modules
+- 13 entity CRUD implementations
diff --git a/frontend/docs/helpers-module.md b/frontend/docs/helpers-module.md
new file mode 100644
index 0000000..329c9a0
--- /dev/null
+++ b/frontend/docs/helpers-module.md
@@ -0,0 +1,738 @@
+# Frontend Helpers Module
+
+## Overview
+
+The Helpers module provides **utility functions** for common operations across the frontend application including data formatting, permission checking, notification handling, text transformation, and file saving.
+
+**Location:** `frontend/src/helpers/`
+
+**Total Files:** 6 files (~298 LOC)
+
+---
+
+## Architecture
+
+```
+frontend/src/helpers/
+├── dataFormatter.js       (176 LOC)  # Entity data formatters for display/edit
+├── userPermissions.ts     (19 LOC)   # RBAC permission checking
+├── notifyStateHandler.ts  (32 LOC)   # Redux notification state handlers
+├── textFormatters.ts      (53 LOC)   # Text transformation utilities
+├── humanize.ts            (12 LOC)   # String humanization
+└── fileSaver.ts           (6 LOC)    # File download trigger
+```
+
+---
+
+## Helper Files
+
+### 1. Data Formatter (`dataFormatter.js`)
+
+**Purpose:** Format entity data for display in tables, lists, and edit forms.
+
+**Lines:** ~210 LOC
+
+**Dependencies:** `dayjs`, `dayjs/plugin/relativeTime`, `lodash`
+
+#### Core Formatters
+
+| Function | Input | Output | Description |
+|----------|-------|--------|-------------|
+| `filesFormatter(arr)` | File array | File array | Pass-through for file arrays |
+| `imageFormatter(arr)` | Image array | `[{ publicUrl }]` | Extract public URLs from images |
+| `oneImageFormatter(arr)` | Image array | `string` | Get first image's public URL |
+| `dateFormatter(date)` | Date/string | `YYYY-MM-DD` | Format date for display |
+| `dateTimeFormatter(date)` | Date/string | `YYYY-MM-DD HH:mm` | Format datetime for display |
+| `relativeTimestamp(date)` | Date/string | Human-readable | Format as relative or absolute time |
+| `booleanFormatter(val)` | boolean | `'Yes'` / `'No'` | Human-readable boolean |
+| `dataGridEditFormatter(obj)` | Object | Object | Transform relations to IDs for DataGrid |
+
+#### Entity Formatters Pattern
+
+Each entity has 4 formatters following this naming convention:
+
+```javascript
+// Display formatters (for table cells/lists)
+[entity]ManyListFormatter(val)   // Array → display names array
+[entity]OneListFormatter(val)    // Object → display name string
+
+// Edit formatters (for form selects)
+[entity]ManyListFormatterEdit(val)  // Array → [{ id, label }]
+[entity]OneListFormatterEdit(val)   // Object → { id, label }
+```
+
+#### Supported Entities
+
+| Entity | Display Field | Formatters |
+|--------|---------------|------------|
+| `users` | `firstName` | 4 formatters |
+| `roles` | `name` | 4 formatters |
+| `permissions` | `name` | 4 formatters |
+| `projects` | `name` | 4 formatters |
+| `assets` | `name` | 4 formatters |
+| `tour_pages` | `name` | 4 formatters |
+| `transitions` | `name` | 4 formatters |
+
+#### Usage Examples
+
+```javascript
+import dataFormatter from '@/helpers/dataFormatter';
+
+// Display in table cell
+const userName = dataFormatter.usersOneListFormatter(user);
+// → "John"
+
+// Display list of roles
+const roleNames = dataFormatter.rolesManyListFormatter(roles);
+// → ["Administrator", "Editor"]
+
+// Format for edit dropdown
+const roleOptions = dataFormatter.rolesManyListFormatterEdit(roles);
+// → [{ id: "uuid-1", label: "Administrator" }, ...]
+
+// Format date
+const formattedDate = dataFormatter.dateFormatter(createdAt);
+// → "2024-03-15"
+
+// Transform object for DataGrid editing
+const editData = dataFormatter.dataGridEditFormatter({
+  name: "Test",
+  project: { id: "uuid", name: "My Project" },
+  tags: [{ id: "1" }, { id: "2" }]
+});
+// → { name: "Test", project: "uuid", tags: ["1", "2"] }
+```
+
+#### relativeTimestamp Method
+
+Formats dates as human-readable relative or absolute timestamps. Uses `dayjs` with the `relativeTime` plugin.
+
+```javascript
+import dayjs from 'dayjs';
+import relativeTime from 'dayjs/plugin/relativeTime';
+dayjs.extend(relativeTime);
+
+relativeTimestamp(date) {
+  if (!date) return '';
+  const d = dayjs(date);
+  const now = dayjs();
+  const diffMinutes = now.diff(d, 'minute');
+  const diffHours = now.diff(d, 'hour');
+
+  // Within last hour
+  if (diffMinutes < 60) {
+    return diffMinutes <= 1 ? 'Just now' : `${diffMinutes} min ago`;
+  }
+
+  // Within last 24 hours
+  if (diffHours < 24) {
+    return `${diffHours} hour${diffHours > 1 ? 's' : ''} ago`;
+  }
+
+  // Format as date + time
+  const isToday = d.isSame(now, 'day');
+  const isYesterday = d.isSame(now.subtract(1, 'day'), 'day');
+  const timeStr = d.format('HH:mm');
+
+  if (isToday) return `Today at ${timeStr}`;
+  if (isYesterday) return `Yesterday at ${timeStr}`;
+  return `${d.format('MMM D')} at ${timeStr}`;
+}
+```
+
+**Output Examples:**
+
+| Time Difference | Output |
+|-----------------|--------|
+| < 2 minutes | `"Just now"` |
+| 5 minutes ago | `"5 min ago"` |
+| 2 hours ago | `"2 hours ago"` |
+| Same day | `"Today at 14:30"` |
+| Yesterday | `"Yesterday at 09:15"` |
+| Older dates | `"Apr 28 at 16:45"` |
+
+**Usage:**
+```javascript
+import dataFormatter from '@/helpers/dataFormatter';
+
+// In publish status buttons
+dataFormatter.relativeTimestamp(lastPublishedAt);
+// → "Just now" or "5 min ago" or "Today at 14:30"
+
+// In constructor menu
+dataFormatter.relativeTimestamp(page.updatedAt);
+// → "2 hours ago"
+```
+
+---
+
+#### dataGridEditFormatter Logic
+
+Transforms nested objects/arrays to their IDs for DataGrid inline editing:
+
+```javascript
+dataGridEditFormatter(obj) {
+  return _.transform(obj, (result, value, key) => {
+    if (_.isArray(value)) {
+      result[key] = _.map(value, 'id');      // Array → array of IDs
+    } else if (_.isObject(value)) {
+      result[key] = value.id;                 // Object → ID string
+    } else {
+      result[key] = value;                    // Primitive → unchanged
+    }
+  });
+}
+```
+
+---
+
+### 2. User Permissions (`userPermissions.ts`)
+
+**Purpose:** Check if current user has required permission(s) for RBAC.
+
+**Lines:** 19 LOC
+
+**Used By:** 48 files (layouts, pages, components, factories)
+
+#### Function Signature
+
+```typescript
+export function hasPermission(
+  user: User,
+  permission_name: string | string[]
+): boolean
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `user` | Object | Current user with `app_role` and `custom_permissions` |
+| `permission_name` | `string` or `string[]` | Permission(s) to check |
+
+#### Logic
+
+1. Returns `false` if user has no role
+2. Returns `true` if no permission specified (permission is optional)
+3. Combines permissions from:
+   - `user.custom_permissions` (direct user permissions)
+   - `user.app_role.permissions` (role-based permissions)
+4. Administrator role has implicit access to all permissions
+5. For array of permissions, returns `true` if user has **any** of them
+
+#### Implementation
+
+```typescript
+export function hasPermission(user, permission_name: string | string[]) {
+  if (!user?.app_role?.name) return false;
+  if (!permission_name) return true;
+
+  // Combine custom + role permissions
+  const permissions = new Set<string>([
+    ...(user?.custom_permissions ?? []).map((p) => p.name),
+    ...(user?.app_role?.permissions ?? []).map((p) => p.name),
+  ]);
+
+  if (typeof permission_name === 'string') {
+    return permissions.has(permission_name) || user.app_role.name === 'Administrator';
+  } else {
+    return permission_name.some((permission) => permissions.has(permission));
+  }
+}
+```
+
+#### Usage Examples
+
+```typescript
+import { hasPermission } from '@/helpers/userPermissions';
+
+// Check single permission
+if (hasPermission(currentUser, 'READ_USERS')) {
+  // Show users list
+}
+
+// Check multiple permissions (OR logic)
+if (hasPermission(currentUser, ['CREATE_PROJECTS', 'UPDATE_PROJECTS'])) {
+  // Show project form
+}
+
+// In layout guard
+<LayoutAuthenticated permission="READ_ASSETS">
+  {page}
+</LayoutAuthenticated>
+
+// Conditional rendering
+{hasPermission(user, 'DELETE_ASSETS') && (
+  <DeleteButton onClick={handleDelete} />
+)}
+```
+
+---
+
+### 3. Notify State Handler (`notifyStateHandler.ts`)
+
+**Purpose:** Manage Redux notification state for async action feedback.
+
+**Lines:** 32 LOC
+
+**Used By:** `createEntitySlice.ts` (affects all 13 entity slices)
+
+#### Functions
+
+| Function | Purpose | Notification Type |
+|----------|---------|-------------------|
+| `resetNotify(state)` | Clear notification state | - |
+| `fulfilledNotify(state, msg)` | Show success message | `'success'` |
+| `rejectNotify(state, action)` | Show error message | `'error'` |
+
+#### State Shape
+
+```typescript
+interface NotificationState {
+  showNotification: boolean;
+  typeNotification: '' | 'success' | 'error' | 'warn';
+  textNotification: string;
+}
+```
+
+#### Implementation
+
+```typescript
+// Clear notification
+export const resetNotify = (state) => {
+  state.notify.showNotification = false;
+  state.notify.typeNotification = '';
+  state.notify.textNotification = '';
+};
+
+// Show success notification
+export const fulfilledNotify = (state, msg) => {
+  state.notify.textNotification = msg;
+  state.notify.typeNotification = 'success';
+  state.notify.showNotification = true;
+};
+
+// Show error notification (handles various error formats)
+export const rejectNotify = (state, action) => {
+  if (typeof action.payload === 'string') {
+    state.notify.textNotification = action.payload;
+  } else if (typeof action === 'object') {
+    // Handle validation errors with field-level messages
+    const obj = { ...action.payload?.errors };
+    delete obj['_errors'];
+
+    let msg = '';
+    for (const key in obj) {
+      msg += `${key}: ${obj[key]['_errors']}; \n `;
+    }
+    state.notify.textNotification = msg;
+  } else {
+    state.notify.textNotification = 'Network error';
+  }
+
+  state.notify.textNotification = state.notify.textNotification || 'Network error';
+  state.notify.typeNotification = 'error';
+  state.notify.showNotification = true;
+};
+```
+
+#### Usage in createEntitySlice
+
+```typescript
+import { resetNotify, fulfilledNotify, rejectNotify } from '../helpers/notifyStateHandler';
+
+// In extraReducers
+builder.addCase(create.pending, (state) => {
+  resetNotify(state);
+});
+
+builder.addCase(create.fulfilled, (state) => {
+  fulfilledNotify(state, 'User has been created');
+});
+
+builder.addCase(create.rejected, (state, action) => {
+  rejectNotify(state, action);
+});
+```
+
+---
+
+### 4. Text Formatters (`textFormatters.ts`)
+
+**Purpose:** Common text transformation utilities for UI display.
+
+**Lines:** 53 LOC
+
+#### Functions
+
+| Function | Input | Output | Example |
+|----------|-------|--------|---------|
+| `singularize(str)` | Plural string | Singular string | `'roles'` → `'role'` |
+| `capitalize(str)` | String | Capitalized string | `'hello'` → `'Hello'` |
+| `snakeToTitle(str)` | snake_case | Title Case | `'tour_pages'` → `'Tour Pages'` |
+| `camelToTitle(str)` | camelCase | Title Case | `'tourPages'` → `'Tour Pages'` |
+
+#### Implementation
+
+```typescript
+/**
+ * Convert a plural title to singular by removing the last character.
+ */
+export function singularize(pluralTitle: string): string {
+  return pluralTitle.slice(0, -1);
+}
+
+/**
+ * Capitalize the first letter of a string.
+ */
+export function capitalize(str: string): string {
+  if (!str) return '';
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Convert snake_case to Title Case.
+ */
+export function snakeToTitle(str: string): string {
+  return str.split('_').map(capitalize).join(' ');
+}
+
+/**
+ * Convert camelCase to Title Case.
+ */
+export function camelToTitle(str: string): string {
+  return str
+    .replace(/([A-Z])/g, ' $1')
+    .trim()
+    .split(' ')
+    .map(capitalize)
+    .join(' ');
+}
+```
+
+#### Usage Examples
+
+```typescript
+import { singularize, capitalize, snakeToTitle, camelToTitle } from '@/helpers/textFormatters';
+
+// Entity name transformations
+singularize('View roles');      // 'View role'
+singularize('users');           // 'user'
+
+// String capitalization
+capitalize('hello world');      // 'Hello world'
+
+// Case conversions
+snakeToTitle('tour_pages');     // 'Tour Pages'
+snakeToTitle('project_audio_tracks'); // 'Project Audio Tracks'
+
+camelToTitle('tourPages');      // 'Tour Pages'
+camelToTitle('projectAudioTracks'); // 'Project Audio Tracks'
+```
+
+---
+
+### 5. Humanize (`humanize.ts`)
+
+**Purpose:** Convert programmatic strings to human-readable format.
+
+**Lines:** 12 LOC
+
+#### Function
+
+```typescript
+export function humanize(str: string): string
+```
+
+#### Transformations
+
+1. Trim leading/trailing spaces and underscores
+2. Replace underscores and multiple spaces with single space
+3. Capitalize first letter
+
+#### Implementation
+
+```typescript
+export function humanize(str: string) {
+  if (!str) return '';
+  return str
+    .toString()
+    .replace(/^[\s_]+|[\s_]+$/g, '')  // Trim spaces/underscores
+    .replace(/[_\s]+/g, ' ')          // Replace _/spaces with single space
+    .replace(/^[a-z]/, function (m) { // Capitalize first letter
+      return m.toUpperCase();
+    });
+}
+```
+
+#### Usage Examples
+
+```typescript
+import { humanize } from '@/helpers/humanize';
+
+humanize('user_name');        // 'User name'
+humanize('_hello_world_');    // 'Hello world'
+humanize('SOME_CONSTANT');    // 'SOME CONSTANT'
+humanize('');                 // ''
+```
+
+---
+
+### 6. File Saver (`fileSaver.ts`)
+
+**Purpose:** Trigger file download in browser.
+
+**Lines:** 6 LOC
+
+**Dependencies:** `file-saver` library
+
+#### Function
+
+```typescript
+export const saveFile = (
+  e: Event,
+  url: string,
+  name: string
+): void
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `e` | Event | Click event (stopped for propagation) |
+| `url` | string | File URL to download |
+| `name` | string | Downloaded filename |
+
+#### Implementation
+
+```typescript
+import { saveAs } from 'file-saver';
+
+export const saveFile = (e, url: string, name: string) => {
+  e.stopPropagation();
+  saveAs(url, name);
+};
+```
+
+#### Usage Examples
+
+```typescript
+import { saveFile } from '@/helpers/fileSaver';
+
+// In a component
+<button onClick={(e) => saveFile(e, asset.cdn_url, asset.name)}>
+  Download
+</button>
+
+// In a table action
+const handleDownload = (e, file) => {
+  saveFile(e, file.publicUrl, file.originalName);
+};
+```
+
+---
+
+## Usage Patterns
+
+### Permission Guard in Layout
+
+```typescript
+// layouts/Authenticated.tsx
+import { hasPermission } from '../helpers/userPermissions';
+
+if (!hasPermission(currentUser, permission)) {
+  router.push('/403');
+  return null;
+}
+```
+
+### Data Formatting in Tables
+
+```typescript
+// In column configuration
+import dataFormatter from '@/helpers/dataFormatter';
+
+const columns = [
+  {
+    field: 'createdAt',
+    valueFormatter: ({ value }) => dataFormatter.dateTimeFormatter(value),
+  },
+  {
+    field: 'project',
+    valueFormatter: ({ value }) => dataFormatter.projectsOneListFormatter(value),
+  },
+  {
+    field: 'isActive',
+    valueFormatter: ({ value }) => dataFormatter.booleanFormatter(value),
+  },
+];
+```
+
+### Notification Handling in Redux
+
+```typescript
+// In entity slice
+import { resetNotify, fulfilledNotify, rejectNotify } from '../helpers/notifyStateHandler';
+
+builder.addCase(deleteItem.pending, (state) => {
+  state.loading = true;
+  resetNotify(state);
+});
+
+builder.addCase(deleteItem.fulfilled, (state) => {
+  state.loading = false;
+  fulfilledNotify(state, 'Item has been deleted');
+});
+
+builder.addCase(deleteItem.rejected, (state, action) => {
+  state.loading = false;
+  rejectNotify(state, action);
+});
+```
+
+### Text Transformation in UI
+
+```typescript
+import { snakeToTitle, singularize } from '@/helpers/textFormatters';
+
+// Generate page title from entity name
+const pageTitle = snakeToTitle(entityName);
+// 'tour_pages' → 'Tour Pages'
+
+// Generate singular form for messages
+const message = `${singularize(entityName)} created`;
+// 'Users' → 'User created'
+```
+
+---
+
+## Helper Dependencies
+
+```
+dataFormatter.js
+├── dayjs (date formatting)
+└── lodash (object transformation)
+
+fileSaver.ts
+└── file-saver (browser download)
+
+userPermissions.ts
+├── Used by: layouts/Authenticated.tsx
+├── Used by: factories/createListPage.tsx
+├── Used by: components/DataGrid/configBuilderFactory.tsx
+└── Used by: 48+ component files
+
+notifyStateHandler.ts
+└── Used by: stores/createEntitySlice.ts
+    └── Affects: All 13 entity slices
+```
+
+---
+
+## File Inventory
+
+| File | LOC | Category | Exports | Used By |
+|------|-----|----------|---------|---------|
+| `dataFormatter.js` | ~210 | Data | 1 default object | 30+ files |
+| `userPermissions.ts` | 19 | Auth | `hasPermission` | 48 files |
+| `notifyStateHandler.ts` | 32 | Redux | 3 functions | createEntitySlice |
+| `textFormatters.ts` | 53 | Text | 4 functions | UI components |
+| `humanize.ts` | 12 | Text | `humanize` | UI components |
+| `fileSaver.ts` | 6 | File | `saveFile` | Download buttons |
+| **Total** | **~332** | | **11 exports** | |
+
+---
+
+## Best Practices
+
+### 1. Use Type-Safe Permission Checks
+
+```typescript
+// Good - explicit permission constant
+import { Permission } from '@/types/permissions';
+hasPermission(user, Permission.READ_USERS);
+
+// Avoid - magic strings
+hasPermission(user, 'READ_USERS');
+```
+
+### 2. Handle Empty Values in Formatters
+
+```typescript
+// dataFormatter handles null/undefined
+const name = dataFormatter.usersOneListFormatter(null);
+// → '' (empty string, not error)
+```
+
+### 3. Use Appropriate Formatter Type
+
+```typescript
+// For display (table cells, lists)
+dataFormatter.rolesOneListFormatter(role);     // → "Administrator"
+
+// For edit forms (dropdowns)
+dataFormatter.rolesOneListFormatterEdit(role); // → { id: "...", label: "Administrator" }
+```
+
+### 4. Consistent Notification Messages
+
+```typescript
+// In createEntitySlice
+fulfilledNotify(state, `${displayName} has been created`);
+fulfilledNotify(state, `${displayName} has been updated`);
+fulfilledNotify(state, `${displayName} has been deleted`);
+```
+
+---
+
+## Adding New Helpers
+
+### Adding Entity Formatter
+
+```javascript
+// In dataFormatter.js
+widgetsManyListFormatter(val) {
+  if (!val || !val.length) return [];
+  return val.map((item) => item.name);
+},
+widgetsOneListFormatter(val) {
+  if (!val) return '';
+  return val.name;
+},
+widgetsManyListFormatterEdit(val) {
+  if (!val || !val.length) return [];
+  return val.map((item) => {
+    return { id: item.id, label: item.name };
+  });
+},
+widgetsOneListFormatterEdit(val) {
+  if (!val) return '';
+  return { label: val.name, id: val.id };
+},
+```
+
+### Adding New Helper File
+
+```typescript
+// helpers/newHelper.ts
+/**
+ * Helper description
+ */
+
+export function helperFunction(input: InputType): OutputType {
+  // Implementation
+}
+
+// No index.ts - import directly from file
+import { helperFunction } from '@/helpers/newHelper';
+```
+
+---
+
+## Related Documentation
+
+- [factories-module.md](./factories-module.md) - Uses hasPermission in createListPage
+- [stores-module.md](./stores-module.md) - Uses notifyStateHandler in createEntitySlice
+- [types-module.md](./types-module.md) - Permission enum types
+- [components-module.md](./components-module.md) - Uses dataFormatter in tables
diff --git a/frontend/docs/hooks-module.md b/frontend/docs/hooks-module.md
new file mode 100644
index 0000000..2b97564
--- /dev/null
+++ b/frontend/docs/hooks-module.md
@@ -0,0 +1,2061 @@
+# Frontend Hooks Module
+
+## Overview
+
+The Hooks module provides **47 custom React hooks** for reusable logic across the frontend application. Hooks handle everything from runtime presentation (preloading, navigation, transitions) to admin pages (tables, forms, filters), the constructor (elements, drag-drop), and React Query data fetching.
+
+**Location:** `frontend/src/hooks/`
+
+**Total Files:** 56 TypeScript files (41 hooks + 13 query hooks + 2 index files)
+
+**Recent Refactors:**
+1. **Page Navigation Consolidation:** 6+ fragmented hooks consolidated into `usePageNavigationState` state machine. See [Navigation State Machine](#usepagenavigationstate) for details.
+2. **Video Hooks Module:** New `hooks/video/` directory with 8 primitive hooks for composable video playback. See [Video Hooks Module](./video-hooks-module.md) for details.
+3. **Preloading Simplification:** Removed neighbor preloading (stream-first approach). Constructor always uses online mode - transition videos stream on-demand, then cache for replay.
+
+---
+
+## State Management Context
+
+**Redux is the default** for app-wide state management. These hooks complement Redux by handling:
+- **Ephemeral state** - Transient UI states that reset on unmount
+- **Computed/derived values** - Data derived from Redux state
+- **DOM interactions** - Refs, observers, event handlers
+- **Session-scoped state** - State that doesn't persist across routes
+
+See [Stores Module - State Management Guidelines](./stores-module.md#state-management-guidelines) for the decision tree on when to use Redux vs local hooks.
+
+**Example:** `usePageNavigation` uses local `useState` because page history is session-scoped and isolated to a single route. If cross-component access or persistence were needed, it would be a Redux slice.
+
+---
+
+## Architecture
+
+```
+frontend/src/hooks/
+├── index.ts                       # Central exports (tree-shaking friendly, 67 LOC)
+│
+├── Runtime/Preloading Hooks (10)
+│   ├── usePreloadOrchestrator.ts      # Main asset preloading coordinator (~720 LOC) [SIMPLIFIED]
+│   ├── usePageNavigationState.ts      # Unified page navigation state machine (~520 LOC)
+│   ├── useTransitionPlayback.ts       # Video transition playback (~795 LOC)
+│   ├── useSlideTransition.ts          # Slide transition animation (~180 LOC)
+│   ├── usePageNavigation.ts           # Page navigation state + history (~195 LOC)
+│   ├── useBackgroundVideoPlayback.ts  # Background video time control + play once (~225 LOC)
+│   ├── useVideoSoundControl.ts        # iOS autoplay sound control (~100 LOC)
+│   ├── usePageDataLoader.ts           # Project/page data loading (~253 LOC)
+│   ├── usePageBackground.ts           # Page background management (~176 LOC)
+│   └── useCanvasScale.ts              # Responsive canvas scaling (~110 LOC)
+│
+│   # DELETED (consolidated into usePageNavigationState):
+│   # - usePageSwitch.ts (~475 LOC)
+│   # - useBackgroundTransition.ts (~164 LOC)
+│   # - useBackgroundUrls.ts (~104 LOC)
+│
+│   # DELETED (simplified preloading - no neighbor traversal):
+│   # - useNeighborGraph.ts (~282 LOC)
+│
+├── Video Hooks (8)
+│   ├── video/index.ts                     # Exports (~60 LOC)
+│   ├── video/useVideoEventManager.ts      # Event listener management (~90 LOC)
+│   ├── video/useVideoBufferingState.ts    # Buffering detection (~180 LOC)
+│   ├── video/useVideoBlobUrl.ts           # Blob URL resolution (~150 LOC)
+│   ├── video/useVideoFirstFrame.ts        # First frame detection (~130 LOC)
+│   ├── video/useVideoErrorRecovery.ts     # Error handling + retry (~160 LOC)
+│   ├── video/useVideoTimeouts.ts          # Timeout management (~80 LOC)
+│   ├── video/useVideoPlaybackCore.ts      # Composite playback logic (~280 LOC)
+│   └── video/useVideoPlayer.ts            # UI video player (~200 LOC)
+│
+├── Audio Hooks (2) - NEW
+│   ├── audio/useAudioEventManager.ts      # Audio event listener management (~115 LOC)
+│   └── useBackgroundAudioPlayback.ts      # Background audio playback + ducking (~220 LOC)
+│
+├── PWA/Offline Hooks (5)
+│   ├── useOfflineMode.ts          # PWA offline management (~468 LOC)
+│   ├── usePWAPreload.ts           # PWA asset preloading (~199 LOC)
+│   ├── useStorageQuota.ts         # Storage quota monitoring (~110 LOC)
+│   ├── useNetworkAware.ts         # Network condition monitoring (~163 LOC)
+│   └── usePreloadProgress.ts      # Preload progress tracking (~220 LOC)
+│
+├── Constructor Hooks (10)
+│   ├── useConstructorElements.ts      # Canvas element CRUD + local clipboard
+│   ├── useCanvasElementDrag.ts        # Element drag handling (~150 LOC)
+│   ├── useConstructorPageActions.ts   # Page save/create/duplicate support
+│   ├── useConstructorData.ts          # Constructor data loading (~150 LOC)
+│   ├── useTransitionPreview.ts        # Transition preview state (~184 LOC)
+│   ├── useTransitionCreation.ts       # Transition creation state (~134 LOC)
+│   ├── useCanvasElapsedTime.ts        # Canvas animation timing (~111 LOC)
+│   ├── useMediaDurationProbe.ts       # Media duration detection (~219 LOC)
+│   └── useBackdropEffect.ts           # Backdrop visual effects (~190 LOC)
+│
+├── Table/List Hooks (3)
+│   ├── useEntityTable.ts          # Complete table state management (~288 LOC)
+│   ├── useFilterItems.ts          # Filter state for data tables (~166 LOC)
+│   └── useCSVHandling.ts          # CSV upload/download operations (~141 LOC)
+│
+├── Form Hooks (2)
+│   ├── useEditPageSync.ts         # Edit page form sync (~166 LOC)
+│   └── useFormSync.ts             # Form state management (~108 LOC)
+│
+├── UI Utility Hooks (10)
+│   ├── useDraggable.ts            # Draggable panel management (~200 LOC)
+│   ├── useOutsideClick.ts         # Click outside detection (~88 LOC)
+│   ├── useElementEffects.ts       # Element interactive effects (~128 LOC)
+│   ├── useIconPreload.ts          # Icon preloading (~176 LOC)
+│   ├── useDashboardCounts.ts      # Dashboard entity counts (~308 LOC)
+│   ├── useDevCompilationStatus.ts # Dev compilation status (~44 LOC)
+│   ├── useProjectAssets.ts        # Project asset URL resolution (~102 LOC)
+│   ├── useAssetOptions.ts         # Asset select options (~119 LOC)
+│   ├── usePublishStatus.ts        # Publish/save timestamp status (~113 LOC)
+│   └── useAudioEffects.ts         # Audio playback on hover/click (~305 LOC)
+│
+├── queries/                       # React Query data fetching hooks (13)
+│   ├── index.ts                   # Query exports (~59 LOC)
+│   ├── useAccessLogsQuery.ts      # Access logs query (~51 LOC)
+│   ├── useAssetVariantsQuery.ts   # Asset variants query (~43 LOC)
+│   ├── useAssetsQuery.ts          # Assets query (~109 LOC)
+│   ├── useElementDefaultsQuery.ts # Element defaults query (~50 LOC)
+│   ├── usePagesQuery.ts           # Tour pages query (~115 LOC)
+│   ├── usePermissionsQuery.ts     # Permissions query (~35 LOC)
+│   ├── useProjectAudioTracksQuery.ts # Audio tracks query (~109 LOC)
+│   ├── useProjectMembershipsQuery.ts # Project memberships query (~94 LOC)
+│   ├── useProjectQuery.ts         # Project query (~84 LOC)
+│   ├── usePublishEventsQuery.ts   # Publish events query (~56 LOC)
+│   ├── usePwaCachesQuery.ts       # PWA caches query (~67 LOC)
+│   ├── useRolesQuery.ts           # Roles query (~112 LOC)
+│   └── useUsersQuery.ts           # Users query (~126 LOC)
+│
+└── Exports
+    └── index.ts                   # Tree-shaking friendly exports
+```
+
+---
+
+## Hook Categories
+
+### 1. Runtime/Preloading Hooks
+
+These hooks power the runtime presentation viewer, handling asset preloading, page switching, and video transitions.
+
+#### usePreloadOrchestrator
+
+**File:** `usePreloadOrchestrator.ts` (~720 LOC)
+
+**Purpose:** Main coordinator for asset preloading with priority queues and blob URL caching. Uses a **stream-first** approach - only preloads current page assets and outgoing transition videos.
+
+```typescript
+interface UsePreloadOrchestratorOptions {
+  pages: PreloadPage[];
+  pageLinks: PreloadPageLink[];
+  elements: PreloadElement[];
+  currentPageId: string | null;
+  pageHistory?: string[];  // Used for detecting back navigation
+  enabled?: boolean;
+}
+
+interface UsePreloadOrchestratorResult {
+  isPreloading: boolean;
+  currentPhase: 'idle' | 'phase1_current_page' | 'phase2_transitions';
+  preloadedUrls: Set<string>;
+  queueLength: number;
+  /** Version counter that increments when blob URLs become ready (triggers re-renders) */
+  readyUrlsVersion: number;
+  preloadAsset: (url: string, priority?: number) => void;
+  clearQueue: () => void;
+  getCachedBlobUrl: (url: string) => Promise<string | null>;
+  isUrlPreloaded: (url: string) => Promise<boolean>;
+  getReadyBlobUrl: (url: string) => string | null;
+}
+```
+
+**Key Features:**
+- **Stream-first approach:** Only preloads current page + outgoing transitions (no neighbor preloading)
+- Priority-based preload queue (transition videos +150, images +100)
+- Two phases: Phase 1 (current page backgrounds) → Phase 2 (transition videos)
+- Dual storage strategy: Cache API (< 5MB) vs IndexedDB (>= 5MB)
+- Presigned URL management with proxy fallback
+- Image pre-decoding for instant display
+- O(1) blob URL lookup via `readyBlobUrlsRef`
+
+**Recent Simplification:**
+The hook was refactored to remove neighbor graph traversal (previously used `useNeighborGraph`). This simplifies the system:
+- Constructor always uses online mode
+- Transition videos stream on-demand, then cache for replay
+- Eliminates network contention from aggressive preloading
+
+**Usage:**
+```typescript
+const preloadOrchestrator = usePreloadOrchestrator({
+  pages,
+  pageLinks,
+  elements,
+  currentPageId,
+  pageHistory,
+  enabled: true,
+});
+
+// Get cached blob URL for instant display
+const blobUrl = preloadOrchestrator.getReadyBlobUrl(originalUrl);
+
+// Manually preload with high priority
+preloadOrchestrator.preloadAsset(transitionVideoUrl, 150);
+```
+
+---
+
+#### usePageNavigationState
+
+**File:** `usePageNavigationState.ts` (~520 LOC)
+
+**Purpose:** Unified state machine for page navigation using `useReducer` for atomic state transitions. Consolidates 6+ fragmented hooks to prevent race conditions.
+
+**Consolidates:**
+- `usePageSwitch` - URL resolution and switching
+- `useBackgroundState` - Background ready tracking
+- `useBackgroundTransition` - Fade-from-black effects
+- `useTransitionCleanup` - Video cleanup coordination
+- `useBackgroundUrls` - URL resolution for display
+- `pageLoadingUtils` - Loading state computation
+
+**State Machine Phases:**
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    PAGE NAVIGATION STATE MACHINE                  │
+├──────────────────────────────────────────────────────────────────┤
+│   ┌───────┐   navigate()   ┌───────────┐                         │
+│   │ IDLE  │ ─────────────► │ PREPARING │                         │
+│   └───────┘                └─────┬─────┘                         │
+│       ▲                    YES /    \ NO (has transition?)       │
+│       │                       ▼      ▼                           │
+│       │            ┌─────────────┐  ┌────────────┐               │
+│       │            │TRANSITIONING│  │ LOADING_BG │               │
+│       │            └──────┬──────┘  └─────┬──────┘               │
+│       │            video ends      onBackgroundReady             │
+│       │                   ▼               │                      │
+│       │            ┌─────────────┐        │                      │
+│       │            │TRANS_DONE   │        │                      │
+│       │            └──────┬──────┘        │                      │
+│       │          onBackgroundReady        │                      │
+│       │                   ▼               ▼                      │
+│       │            ┌────────────────────────┐                    │
+│       │            │       FADING_IN        │                    │
+│       │            └───────────┬────────────┘                    │
+│       │               fade complete                              │
+│       └────────────────────────┘                                 │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+```typescript
+type NavigationPhase =
+  | 'idle'           // No navigation in progress
+  | 'preparing'      // Resolving URLs, saving previous state
+  | 'transitioning'  // Video transition playing
+  | 'transition_done'// Video finished, waiting for background
+  | 'loading_bg'     // Direct navigation, waiting for background
+  | 'fading_in';     // Black overlay fading out
+
+interface UsePageNavigationStateResult {
+  // Current state
+  phase: NavigationPhase;
+
+  // Current page URLs (for display)
+  currentImageUrl: string;
+  currentVideoUrl: string;
+  currentAudioUrl: string;
+
+  // Previous page URLs (for overlay)
+  previousImageUrl: string;
+  previousVideoUrl: string;
+
+  // Derived states (computed from phase)
+  isLoading: boolean;
+  showSpinner: boolean;
+  showElements: boolean;
+  showPreviousOverlay: boolean;
+  showTransitionVideo: boolean;
+  isFadingIn: boolean;
+  isSwitching: boolean;
+  isNewBgReady: boolean;
+  isBackgroundReady: boolean;
+  pendingTransitionComplete: boolean;
+
+  // Transition style for CSS
+  transitionStyle: React.CSSProperties;
+
+  // Actions
+  navigateToPage: (targetPage, options?) => Promise<void>;
+  onBackgroundReady: () => void;
+  onTransitionEnded: () => void;
+  setBackgroundDirectly: (imageUrl, videoUrl, audioUrl) => void;
+  onVideoBufferStateChange: (isBuffering: boolean) => void;
+}
+```
+
+**Key Benefits:**
+| Before | After |
+|--------|-------|
+| 6+ hooks with 15+ state variables | 1 hook with 1 state object |
+| Race conditions from async setState | Atomic transitions via useReducer |
+| Invalid flag combinations possible | State machine prevents invalid states |
+| Derived state scattered | All derived state in one useMemo |
+| Hard to debug | Single phase value to inspect |
+
+**Usage:**
+```typescript
+const navState = usePageNavigationState({
+  preloadCache: preloadOrchestrator
+    ? {
+        getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,
+        getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+        preloadedUrls: preloadOrchestrator.preloadedUrls,
+      }
+    : undefined,
+  transitionSettings,
+});
+
+// Navigate to a page
+await navState.navigateToPage(targetPage, {
+  hasTransition: false,
+  isBack: false,
+  onSwitched: () => applyPageSelection(targetPage.id, false),
+});
+
+// Use in CanvasBackground
+<CanvasBackground
+  backgroundImageUrl={navState.currentImageUrl}
+  backgroundVideoUrl={navState.currentVideoUrl}
+  previousBgImageUrl={navState.previousImageUrl}
+  isSwitching={navState.isSwitching}
+  isNewBgReady={navState.isNewBgReady}
+  onBackgroundReady={navState.onBackgroundReady}
+/>
+```
+
+**Context Provider:**
+A `PageNavigationContext` is available for components that need access to navigation state:
+
+```typescript
+import { PageNavigationProvider, usePageNavigationContext } from '../context/PageNavigationContext';
+
+// In parent component
+<PageNavigationProvider preloadCache={...} transitionSettings={...}>
+  <CanvasBackground />
+  <Elements />
+</PageNavigationProvider>
+
+// In child component
+const { phase, onBackgroundReady } = usePageNavigationContext();
+```
+
+---
+
+#### useTransitionPlayback
+
+**File:** `useTransitionPlayback.ts` (~795 LOC)
+
+**Purpose:** Coordinates video transition playback with forward and pre-generated reversed video support.
+
+```typescript
+interface TransitionPlaybackOptions {
+  transition: TransitionPreviewState | null;
+  pendingPageId: string;
+  transitionVideoRef: React.RefObject<HTMLVideoElement | null>;
+  preloadOrchestrator?: UsePreloadOrchestratorResult;
+  onTransitionComplete: (targetPageId: string) => void;
+  onTransitionError?: (error: string) => void;
+}
+
+interface TransitionPlaybackResult {
+  isPlaying: boolean;
+  play: () => Promise<void>;
+  stop: () => void;
+  pendingTransitionComplete: boolean;
+}
+```
+
+**Reverse Modes:**
+| Mode | Description |
+|------|-------------|
+| `none` | Forward playback only |
+| `separate` | Use pre-generated reversed video (server-side FFmpeg reversal) |
+
+Reversed videos are pre-generated on the server when pages are saved, using
+FFmpeg for audio/video synchronization.
+
+**Source URL Selection:**
+```typescript
+const sourceUrl = useMemo(() => {
+  if (!transition) return '';
+  // Use reversed video if back navigation with separate reversed video
+  if (transition.isBack && transition.reverseVideoUrl) {
+    return transition.reverseVideoUrl;
+  }
+  return transition.videoUrl;
+}, [transition]);
+```
+
+**Usage:**
+```typescript
+const transitionPlayback = useTransitionPlayback({
+  transition: transitionPreview,
+  pendingPageId,
+  transitionVideoRef,
+  preloadOrchestrator,
+  onTransitionComplete: (targetId) => {
+    pageSwitch.switchToPage(pages.find(p => p.id === targetId));
+    transitionPreviewHook.closePreview();
+  },
+});
+```
+
+---
+
+#### useSlideTransition
+
+**File:** `useSlideTransition.ts` (~180 LOC)
+
+**Purpose:** Manages slide transition animation state for Gallery and Carousel elements. Implements fade-through-overlay animation pattern.
+
+**Animation Phases:**
+```
+Phase 1: Fade Out (half duration)
+├── overlayOpacity: 0 → 1
+└── slideOpacity: 1 → 0
+
+Phase 2: Swap (at midpoint)
+└── displayIndex switches to new slide
+
+Phase 3: Fade In (half duration)
+├── overlayOpacity: 1 → 0
+└── slideOpacity: 0 → 1
+```
+
+```typescript
+interface UseSlideTransitionReturn {
+  currentIndex: number;        // Logical current index
+  displayIndex: number;        // Visual index (lags during transition)
+  phase: 'idle' | 'fadingOut' | 'fadingIn';
+  isTransitioning: boolean;
+  overlayOpacity: number;      // 0-1
+  overlayColor: string;        // From settings
+  goToIndex: (index: number) => void;
+  setInitialIndex: (index: number) => void;
+  slideTransitionStyle: CSSProperties;
+  overlayTransitionStyle: CSSProperties;
+  slideOpacity: number;        // Current slide visibility
+}
+```
+
+**Usage:**
+```typescript
+import { useSlideTransition } from '../hooks/useSlideTransition';
+import { resolveSlideTransition, extractCarouselSlideOverride } from '../lib/resolveSlideTransition';
+
+// Resolve settings with cascade
+const slideSettings = resolveSlideTransition(
+  pageTransitionSettings,
+  extractCarouselSlideOverride(element),
+);
+
+const {
+  displayIndex,
+  goToIndex,
+  overlayOpacity,
+  overlayColor,
+  slideTransitionStyle,
+  overlayTransitionStyle,
+  slideOpacity,
+} = useSlideTransition(slideSettings);
+
+// Navigate
+const handleNext = () => goToIndex((currentIndex + 1) % slides.length);
+
+// Render
+<img style={{ ...slideTransitionStyle, opacity: slideOpacity }} src={slides[displayIndex].imageUrl} />
+<div style={{ ...overlayTransitionStyle, opacity: overlayOpacity, backgroundColor: overlayColor }} />
+```
+
+---
+
+> **Note:** Runtime preloading is stream-first: the system preloads current page
+> assets and outgoing transition videos.
+
+---
+
+#### usePageNavigation
+
+**File:** `usePageNavigation.ts` (~195 LOC)
+
+**Purpose:** Manages page navigation state with optional history tracking. Used by both `RuntimePresentation.tsx` and `constructor.tsx` for unified history management.
+
+```typescript
+interface UsePageNavigationResult<TPage extends NavigablePage> {
+  currentPageId: string | null;
+  currentPage: TPage | null;
+  pageHistory: string[];
+  previousPageId: string | null;
+  defaultPage: TPage | null;
+  setCurrentPageId: (pageId: string) => void;
+  applyPageSelection: (targetPageId: string, isBack?: boolean) => void;
+  isBackNavigation: (targetPageId: string) => boolean;
+  goBack: () => boolean;
+  resetHistory: () => void;
+  /** Get navigation context for history-based back navigation */
+  getNavigationContext: () => NavigationContext;
+}
+```
+
+**Key Features:**
+- **History limit**: `MAX_HISTORY_LENGTH = 50` prevents unbounded growth in long sessions
+- **Browser-like back navigation**: History pops when `isBack=true` and target matches previous page
+- **Navigation context**: `getNavigationContext()` provides `{ currentPageSlug, previousPageId }` for `resolveNavigationTarget()`
+- **Unified state management**: Single source of truth for both constructor and runtime presentation
+
+**Usage:**
+```typescript
+// Runtime mode with history (RuntimePresentation.tsx)
+const {
+  currentPageId: selectedPageId,
+  pageHistory,
+  applyPageSelection,
+  getNavigationContext,
+} = usePageNavigation({
+  pages,
+  defaultPageId: initialPageId,
+  trackHistory: true,
+});
+
+// Constructor mode with history (constructor.tsx)
+const {
+  currentPageId: activePageId,
+  pageHistory,
+  applyPageSelection,
+  getNavigationContext,
+  setCurrentPageId: setActivePageId,
+} = usePageNavigation({
+  pages,
+  trackHistory: true,
+});
+
+// Navigate with back flag (history pops on back)
+applyPageSelection(targetPageId, isBack);
+
+// Get context for history-based navigation
+const navContext = getNavigationContext();
+const navTarget = resolveNavigationTarget(element, pages, navContext);
+
+// Go back programmatically
+if (nav.goBack()) {
+  console.log('Went back to', nav.previousPageId);
+}
+```
+
+**History Behavior:**
+```
+Forward: A → B → C → history: [A, B, C]
+Back to B (isBack=true): → history: [A, B]  ✓ Pops C
+Back to A (isBack=true): → history: [A]     ✓ Pops B
+Forward to D: → history: [A, D]             ✓ Adds D
+```
+
+---
+
+> **Note:** `useBackgroundTransition` has been consolidated into `usePageNavigationState`. See [usePageNavigationState](#usepagenavigationstate) for the unified state machine.
+
+---
+
+#### useBackgroundVideoPlayback
+
+**File:** `useBackgroundVideoPlayback.ts` (~225 LOC)
+
+**Purpose:** Manages background video playback with custom start/end time control and "play once" functionality for tour pages.
+
+```typescript
+interface UseBackgroundVideoPlaybackOptions {
+  videoUrl?: string;
+  autoplay?: boolean;    // Default: true
+  loop?: boolean;        // Default: true
+  muted?: boolean;       // Default: true
+  startTime?: number | null;  // Start playback at this time (seconds)
+  endTime?: number | null;    // Stop/loop at this time (seconds)
+  playOnce?: boolean;    // Default: false - play only once per session
+  pageId?: string;       // Required for playOnce tracking
+}
+
+interface UseBackgroundVideoPlaybackResult {
+  videoRef: RefObject<HTMLVideoElement | null>;
+}
+```
+
+**Key Features:**
+- Handles `loadedmetadata` event for initial seek to `startTime`
+- Uses `timeupdate` event to enforce `endTime` boundary
+- When `endTime` is set, handles looping via JavaScript (seeks back to `startTime`)
+- Autoplay with browser policy handling (catch and ignore)
+- **Play Once Mode:** When `playOnce` is true and `pageId` is provided:
+  - Tracks played pages in a module-level `Set<string>` (`playedOncePages`)
+  - On first visit: video plays normally, page ID added to Set on `ended` event
+  - On subsequent visits: video seeks to last frame and pauses immediately
+  - Session-scoped (resets on browser refresh, not persisted to storage)
+
+**Usage:**
+```typescript
+const { videoRef } = useBackgroundVideoPlayback({
+  videoUrl: page.background_video_url,
+  autoplay: page.background_video_autoplay ?? true,
+  loop: page.background_video_loop ?? true,
+  muted: page.background_video_muted ?? true,
+  startTime: page.background_video_start_time ?? null,
+  endTime: page.background_video_end_time ?? null,
+  playOnce: page.background_video_play_once ?? false,
+  pageId: page.id,  // Required for play-once tracking
+});
+
+// Render video with ref
+<video
+  ref={videoRef}
+  src={videoUrl}
+  autoPlay={autoplay}
+  loop={endTime == null ? loop : false}  // Use JS loop when endTime is set
+  muted={muted}
+  playsInline
+/>
+```
+
+**Note:** When `endTime` is set, native HTML5 `loop` attribute should be disabled to allow the hook to handle looping via `timeupdate` event, properly seeking back to `startTime`.
+
+---
+
+#### useVideoSoundControl
+
+**File:** `useVideoSoundControl.ts` (~100 LOC)
+
+**Purpose:** Manages global presentation sound state with iOS autoplay compatibility. Presentation audio starts muted so visual media can autoplay, then background audio/video, element hover/click effects, media players, and gallery/info-panel videos can be unmuted by user interaction via a custom sound button.
+
+```typescript
+interface UseVideoSoundControlOptions {
+  pageHasSound: boolean;        // Whether page settings allow sound
+  hasBackgroundVideo: boolean;  // Whether page has a background video
+  hasBackgroundAudio?: boolean; // Whether page has ambient/background audio
+  hasElementAudio?: boolean;    // Whether elements can produce sound
+  hasPresentationAudio?: boolean; // Whether any page in the presentation can produce sound
+}
+
+interface UseVideoSoundControlResult {
+  isMuted: boolean;            // Current muted state (starts true)
+  showSoundButton: boolean;    // Whether to show sound toggle button
+  toggleSound: () => void;     // Toggle muted state
+  setMuted: (muted: boolean) => void; // Force muted state
+}
+```
+
+**Key Features:**
+- Always starts muted for iOS autoplay compatibility
+- Shows sound button when background video sound, background audio, element
+  audio/video sound, or presentation-level audio exists
+- Works with `RuntimeControls` sound toggle button
+- Used by runtime presentations and constructor interact mode
+
+**Usage:**
+```tsx
+const soundControl = useVideoSoundControl({
+  pageHasSound: page.background_video_muted === false,
+  hasBackgroundVideo: Boolean(backgroundVideoUrl),
+  hasBackgroundAudio: Boolean(backgroundAudioUrl),
+  hasPresentationAudio,
+});
+
+// Pass to CanvasBackground (always starts muted)
+<CanvasBackground videoMuted={soundControl.isMuted} />
+
+// Pass to RuntimeControls (sound toggle button)
+<RuntimeControls
+  showSoundButton={soundControl.showSoundButton}
+  isMuted={soundControl.isMuted}
+  onSoundToggle={soundControl.toggleSound}
+/>
+```
+
+**iOS Autoplay Policy:**
+- iOS WebKit blocks autoplay for unmuted videos
+- By starting muted + providing custom sound button, native controls are avoided
+- CSS in `main.css` hides native `-webkit-media-controls-*` as fallback
+
+---
+
+### Audio Hooks
+
+#### useAudioEventManager
+
+**File:** `audio/useAudioEventManager.ts` (~115 LOC)
+
+**Purpose:** Manages audio element event listener setup and cleanup with a declarative API. Mirrors the `useVideoEventManager` pattern for consistency.
+
+```typescript
+interface UseAudioEventManagerOptions {
+  audioRef: RefObject<HTMLAudioElement | null>;
+  enabled?: boolean;
+  handlers: AudioEventHandlers;
+}
+
+interface AudioEventHandlers {
+  onLoadedMetadata?: (event: Event) => void;
+  onLoadedData?: (event: Event) => void;
+  onCanPlay?: (event: Event) => void;
+  onPlaying?: (event: Event) => void;
+  onPause?: (event: Event) => void;
+  onEnded?: (event: Event) => void;
+  onTimeUpdate?: (event: Event) => void;
+  onError?: (event: Event) => void;
+  // ... other audio events
+}
+```
+
+**Usage:**
+```typescript
+useAudioEventManager({
+  audioRef,
+  enabled: Boolean(audioUrl),
+  handlers: {
+    onLoadedMetadata: () => seekToStartTime(),
+    onTimeUpdate: () => enforceEndTime(),
+    onEnded: () => markAsPlayed(),
+  },
+});
+```
+
+---
+
+#### useBackgroundAudioPlayback
+
+**File:** `useBackgroundAudioPlayback.ts` (~220 LOC)
+
+**Purpose:** Manages background audio playback with custom start/end time control, session-scoped "play once" tracking, and integration with audio ducking system.
+
+```typescript
+interface UseBackgroundAudioPlaybackOptions {
+  audioUrl?: string;              // Audio URL (may be blob URL)
+  audioStoragePath?: string;      // Original storage path for play-once tracking
+  autoplay?: boolean;             // Default: true
+  loop?: boolean;                 // Default: true
+  startTime?: number | null;      // Start playback at time (seconds)
+  endTime?: number | null;        // Stop/loop at time (seconds)
+  paused?: boolean;               // External pause control (for ducking)
+}
+
+interface UseBackgroundAudioPlaybackResult {
+  audioRef: RefObject<HTMLAudioElement | null>;
+  shouldBlockAutoplay: boolean;   // True if audio already played this session
+}
+```
+
+**Key Features:**
+- **Start/End Time Control:** Seeks to `startTime` on load, loops or pauses at `endTime`
+- **Play Once Tracking:** Session-scoped Set tracks played audio (cleared on browser refresh)
+- **Audio Ducking Integration:** Registers with `backgroundAudioController` for automatic pause/resume when element audio plays
+- **Graceful Autoplay:** Handles browser autoplay restrictions silently
+
+**Usage:**
+```typescript
+const { audioRef } = useBackgroundAudioPlayback({
+  audioUrl: page.background_audio_url,
+  autoplay: page.background_audio_autoplay ?? true,
+  loop: page.background_audio_loop ?? true,
+  startTime: page.background_audio_start_time ?? null,
+  endTime: page.background_audio_end_time ?? null,
+});
+
+// Render audio with ref
+<audio ref={audioRef} src={audioUrl} preload="auto" hidden />
+```
+
+**Audio Ducking:** When element hover/click audio starts playing, background audio is automatically paused via `backgroundAudioController`. When element audio ends, background audio resumes.
+
+---
+
+#### useCanvasScale
+
+**File:** `useCanvasScale.ts` (~110 LOC)
+
+**Purpose:** Manages responsive canvas scaling with letterbox mode for maintaining design aspect ratio across different viewport sizes. Core hook of the UI Adaptivity System.
+
+> **See:** [UI Adaptivity System](ui-adaptivity-system.md) for complete documentation including canvas units, letterbox mode, and element styling.
+
+```typescript
+interface UseCanvasScaleOptions {
+  designWidth?: number;    // Design canvas width (default: 1920)
+  designHeight?: number;   // Design canvas height (default: 1080)
+}
+
+interface UseCanvasScaleResult {
+  scale: number;                    // Current scale factor (1.0 = design size)
+  designWidth: number;              // Design width (from options or default)
+  designHeight: number;             // Design height (from options or default)
+  canvasWidth: number;              // Actual canvas width in pixels
+  canvasHeight: number;             // Actual canvas height in pixels
+  isPortrait: boolean;              // Whether viewport is portrait orientation
+  showRotatePrompt: boolean;        // Whether to show rotate prompt
+  cssVars: CSSProperties;           // CSS custom properties for scaling
+  letterboxStyles: CSSProperties;   // Styles for centered letterbox container
+}
+```
+
+**Key Features:**
+- Calculates scale factor: `min(viewportWidth/designWidth, viewportHeight/designHeight)`
+- Provides CSS custom properties (`--cu`, `--canvas-scale`, `--design-width`, `--design-height`)
+- Generates letterbox styles for centered canvas with black bars
+- Handles portrait orientation detection with rotate prompt
+
+**CSS Custom Properties:**
+| Property | Description | Example |
+|----------|-------------|---------|
+| `--cu` | Canvas unit (1 design pixel) | `calc(1px * 0.75)` |
+| `--canvas-scale` | Current scale factor | `0.75` |
+| `--design-width` | Design canvas width | `1920` |
+| `--design-height` | Design canvas height | `1080` |
+
+**Usage:**
+```typescript
+const { cssVars, letterboxStyles, isPortrait, showRotatePrompt } = useCanvasScale({
+  designWidth: project?.design_width,
+  designHeight: project?.design_height,
+});
+
+// Apply to canvas container
+<div className="bg-black w-screen h-screen overflow-hidden">
+  <div style={{ ...cssVars, ...letterboxStyles }}>
+    {/* Canvas content - all children can use var(--cu) */}
+  </div>
+</div>
+```
+
+**Integration with Element Styles:**
+```typescript
+import { toCU } from '../lib/canvasScale';
+
+// Elements use canvas units for responsive sizing
+<button style={{
+  fontSize: toCU(16),      // "calc(16 * var(--cu, 1px))"
+  padding: toCU(12),       // Scales with viewport
+  borderRadius: toCU(8),
+}}>
+  Click me
+</button>
+```
+
+---
+
+#### usePageDataLoader
+
+**File:** `usePageDataLoader.ts` (~253 LOC)
+
+**Purpose:** Loads project and page data for runtime and constructor.
+
+```typescript
+interface UsePageDataLoaderResult {
+  project: Project | null;
+  pages: TourPage[];
+  elements: CanvasElement[];
+  pageLinks: PreloadPageLink[];
+  isLoading: boolean;
+  error: string | null;
+  reload: (preservePageId?: string) => Promise<void>;
+}
+```
+
+---
+
+### 2. PWA/Offline Hooks
+
+Hooks for Progressive Web App functionality including offline caching and network monitoring.
+
+#### useOfflineMode
+
+**File:** `useOfflineMode.ts` (~468 LOC)
+
+**Purpose:** Full offline mode management with download progress tracking.
+
+```typescript
+interface UseOfflineModeOptions {
+  projectId: string | null;
+  projectSlug?: string;
+  projectName?: string;
+  enabled?: boolean;
+}
+
+interface UseOfflineModeResult {
+  // Status
+  isOfflineCapable: boolean;
+  isDownloaded: boolean;
+  isDownloading: boolean;
+  status: ProjectOfflineStatus;
+  progress: number;
+  downloadedAssets: number;
+  totalAssets: number;
+  downloadedBytes: number;
+  totalBytes: number;
+  error: string | null;
+
+  // Actions
+  startDownload: () => Promise<void>;
+  pauseDownload: () => void;
+  resumeDownload: () => void;
+  cancelDownload: () => void;
+  deleteOfflineData: () => Promise<void>;
+  checkForUpdates: () => Promise<boolean>;
+
+  // Info
+  projectInfo: OfflineProject | null;
+  estimatedSize: number;
+  formatSize: (bytes: number) => string;
+}
+```
+
+**Usage:**
+```typescript
+const offlineMode = useOfflineMode({
+  projectId,
+  projectSlug,
+  projectName,
+  enabled: true,
+});
+
+// Start download
+await offlineMode.startDownload();
+
+// Check progress
+console.log(`Downloaded: ${offlineMode.progress}%`);
+console.log(`${offlineMode.downloadedAssets}/${offlineMode.totalAssets} assets`);
+console.log(`Size: ${offlineMode.formatSize(offlineMode.downloadedBytes)}`);
+```
+
+---
+
+#### useStorageQuota
+
+**File:** `useStorageQuota.ts` (~110 LOC)
+
+**Purpose:** Monitors storage quota and usage for offline assets.
+
+```typescript
+interface UseStorageQuotaResult extends StorageQuotaInfo {
+  isLoading: boolean;
+  error: string | null;
+  refresh: () => Promise<void>;
+  requestPersistence: () => Promise<boolean>;
+  isPersisted: boolean;
+  isWarning: boolean;   // >= warningPercent (default 70%)
+  isCritical: boolean;  // >= criticalPercent (default 90%)
+  formatSize: (bytes: number) => string;
+}
+```
+
+---
+
+#### useNetworkAware
+
+**File:** `useNetworkAware.ts` (~163 LOC)
+
+**Purpose:** Monitors network conditions and adapts preloading strategy.
+
+```typescript
+interface UseNetworkAwareResult {
+  networkInfo: NetworkInfo;
+  shouldPreloadAggressively: boolean;  // 4G or high downlink
+  preferLowQuality: boolean;           // slow-2g, 2g, or saveData
+  recommendedConcurrency: number;      // 1-3 based on connection
+  suggestOfflineMode: boolean;         // Poor connection detected
+}
+```
+
+**Network Concurrency Table:**
+| Connection | Concurrency |
+|------------|-------------|
+| slow-2g | 1 |
+| 2g | 1 |
+| 3g | 2 |
+| 4g | 3 |
+
+---
+
+#### usePWAPreload
+
+**File:** `usePWAPreload.ts` (~199 LOC)
+
+**Purpose:** Orchestrates asset preloading for PWA offline caching with progress tracking.
+
+```typescript
+interface PreloadState {
+  isPreloading: boolean;
+  progress: number;
+  loadedCount: number;
+  totalCount: number;
+  errors: string[];
+}
+
+const result = usePWAPreload({
+  assets: [
+    { url: 'image.jpg', type: 'image' },
+    { url: 'video.mp4', type: 'video' },
+  ],
+  onComplete: () => console.log('Done!'),
+  skipIfCached: true,
+});
+```
+
+---
+
+### 3. Constructor Hooks
+
+Hooks for the visual tour builder (constructor.tsx).
+
+#### useConstructorElements
+
+**File:** `useConstructorElements.ts`
+
+**Purpose:** Canvas element CRUD operations with selection management, nested
+gallery/carousel/info-panel item helpers, and constructor-local element
+copy/paste clipboard.
+
+```typescript
+interface UseConstructorElementsOptions {
+  initialElements?: CanvasElement[];
+  elementDefaultsByType?: Partial<Record<CanvasElementType, Partial<CanvasElement>>>;
+  allowedNavigationTypes?: NavigationElementType[];
+  onElementsChange?: (elements: CanvasElement[]) => void;
+  initialSelectedElementId?: string;
+  onElementSelected?: (elementId: string) => void;
+  onSelectionCleared?: () => void;
+  onElementAdded?: (element: CanvasElement) => void;
+  onElementRemoved?: (elementId: string) => void;
+  onElementCopied?: (element: CanvasElement) => void;
+  onElementPasted?: (element: CanvasElement) => void;
+}
+
+interface UseConstructorElementsResult {
+  elements: CanvasElement[];
+  setElements: React.Dispatch<React.SetStateAction<CanvasElement[]>>;
+  getElements: () => CanvasElement[];
+  selectedElementId: string;
+  selectedElement: CanvasElement | null;
+  copiedElement: CanvasElement | null;
+  canPasteElement: boolean;
+  selectElement: (elementId: string) => void;
+  clearSelection: () => void;
+  addElement: (type: CanvasElementType) => void;
+  updateSelectedElement: (patch: Partial<CanvasElement>) => void;
+  updateElement: (elementId: string, patch: Partial<CanvasElement>) => void;
+  removeSelectedElement: () => void;
+  copySelectedElement: () => void;
+  pasteCopiedElement: () => CanvasElement | null;
+  removeElement: (elementId: string) => void;
+
+  // Gallery cards
+  galleryCards: {
+    add: () => void;
+    update: (cardId: string, patch: Partial<GalleryCard>) => void;
+    remove: (cardId: string) => void;
+  };
+
+  // Gallery info spans
+  galleryInfoSpans: {
+    add: () => void;
+    update: (spanId: string, text: string) => void;
+    remove: (spanId: string) => void;
+  };
+
+  // Carousel slides
+  carouselSlides: {
+    add: () => void;
+    update: (slideId: string, patch: Partial<CarouselSlide>) => void;
+    remove: (slideId: string) => void;
+  };
+
+  updateElementPosition: (elementId: string, xPercent: number, yPercent: number) => void;
+  bringToFront: (elementId: string) => void;
+  sendToBack: (elementId: string) => void;
+}
+```
+
+`setElements` is wrapped by the hook so it updates both React state and an
+internal `elementsRef`. `getElements()` reads that ref synchronously. This is
+required for same-tick flows such as Paste followed immediately by Save or Save
+to Stage, where React may not have committed the visible re-render yet.
+
+Element copy/paste uses `cloneElementForPaste()` from `lib/elementDefaults.ts`.
+The clone preserves all non-identity settings, including CSS styles, effects,
+media, links, navigation targets, transition fields, dimensions, and position.
+Only the top-level element ID and nested gallery/carousel/info-panel item IDs are
+regenerated.
+
+**Usage:**
+```typescript
+const {
+  elements,
+  getElements,
+  selectedElement,
+  addElement,
+  updateSelectedElement,
+  updateElement,
+  copySelectedElement,
+  pasteCopiedElement,
+  canPasteElement,
+  galleryCards,
+  galleryInfoSpans,
+} = useConstructorElements({
+  initialElements,
+  onElementsChange: setElements,
+  elementDefaultsByType,
+});
+
+// Add a button element
+addElement('button');
+
+// Update selected element
+updateSelectedElement({ label: 'New Label' });
+
+// Update element by ID
+updateElement(elementId, { xPercent: 50 });
+
+// Add gallery card to selected gallery
+galleryCards.add();
+
+// Add info span to selected gallery
+galleryInfoSpans.add();
+
+// Toolbar copy/paste actions
+copySelectedElement();
+if (canPasteElement) pasteCopiedElement();
+```
+
+---
+
+#### useCanvasElementDrag
+
+**File:** `useCanvasElementDrag.ts` (~150 LOC)
+
+**Purpose:** Handles element dragging on the constructor canvas.
+
+```typescript
+interface UseCanvasElementDragResult {
+  isDragging: boolean;
+  onDragStart: (event: React.MouseEvent, elementId: string) => void;
+  onDragEnd: () => void;
+}
+```
+
+**Usage:**
+```typescript
+const { isDragging, onDragStart, onDragEnd } = useCanvasElementDrag({
+  canvasRef,
+  elements,
+  onPositionChange: (elementId, xPercent, yPercent) => {
+    updateElementPosition(elementId, xPercent, yPercent);
+  },
+});
+
+// Attach to element
+<div
+  onMouseDown={(e) => onDragStart(e, element.id)}
+  onMouseUp={onDragEnd}
+>
+```
+
+---
+
+#### useConstructorPageActions
+
+**File:** `useConstructorPageActions.ts`
+
+**Purpose:** Page create/save/publish operations in constructor, including page
+duplication orchestration.
+
+```typescript
+interface UseConstructorPageActionsOptions {
+  activePageId: string;
+  elements: CanvasElement[];
+  getElements?: () => CanvasElement[];
+  pageBackground: PageBackgroundState;
+  onReload: () => Promise<void>;
+}
+
+interface UseConstructorPageActionsResult {
+  isSaving: boolean;
+  isSavingToStage: boolean;
+  isCreatingPage: boolean;
+  isDuplicatingPage: boolean;
+  isCreatingTransition: boolean;
+  saveConstructor: () => Promise<void>;
+  saveToStage: () => Promise<void>;
+  createPage: () => Promise<void>;
+  duplicatePage: (sourcePageId: string, name: string, slug: string) => Promise<TourPage | null>;
+  createTransition: (params: TransitionParams) => Promise<void>;
+}
+```
+
+`saveConstructor()` serializes `getElements?.() ?? elements` into
+`tour_pages.ui_schema_json.elements`. Passing `getElements` from
+`useConstructorElements` keeps pasted elements from being dropped if Save/Stage
+is clicked immediately after Paste.
+
+Page duplication saves the active page first, then calls
+`POST /api/tour_pages/:id/duplicate`; the backend creates an independent dev
+page at the end of the presentation order. Page deletion itself is triggered
+from `constructor.tsx` so the page can show the shared confirmation modal and
+choose the next active page after the API call.
+
+---
+
+#### useTransitionPreview
+
+**File:** `useTransitionPreview.ts` (~200 LOC)
+
+**Purpose:** Manages transition video preview state in constructor.
+
+```typescript
+interface UseTransitionPreviewResult {
+  preview: TransitionPreviewState | null;
+  pendingPageId: string;
+  openPreview: (element: TransitionElement, direction: 'forward' | 'back') => void;
+  openPreviewWithTarget: (element: TransitionElement, direction: 'forward' | 'back', targetPageId: string) => void;
+  closePreview: () => void;
+  isActive: boolean;
+}
+```
+
+---
+
+### 4. Table/List Hooks
+
+Hooks for admin data tables.
+
+#### useEntityTable
+
+**File:** `useEntityTable.ts` (~296 LOC)
+
+**Purpose:** Complete state management for entity data tables.
+
+```typescript
+interface UseEntityTableReturn<T> {
+  data: T[];
+  columns: GridColDef[];
+  loading: boolean;
+  count: number;
+
+  // Pagination
+  currentPage: number;
+  setCurrentPage: (page: number) => void;
+  numPages: number;
+
+  // Sorting
+  sortModel: GridSortModel;
+  setSortModel: (model: GridSortModel) => void;
+
+  // Selection
+  selectedRows: string[];
+  setSelectedRows: (ids: string[]) => void;
+
+  // Filtering
+  filterItems: FilterItem[];
+  handleFilterSubmit: () => void;
+  handleFilterReset: () => void;
+
+  // Actions
+  handleDeleteClick: (id: string) => void;
+  handleDeleteConfirm: () => Promise<void>;
+  handleRowUpdate: (id: string, data: Partial<T>) => Promise<void>;
+
+  // Data loading
+  loadData: (page?: number, request?: string) => void;
+}
+```
+
+**Usage:**
+```typescript
+const tableProps = useEntityTable<User>({
+  entityName: 'users',
+  entityNamePlural: 'users',
+  fetchAction: usersFetch,
+  deleteAction: usersDelete,
+  configureColumns: configureUsersCols,
+  filters: usersFilters,
+});
+
+// In component
+<DataGrid
+  rows={tableProps.data}
+  columns={tableProps.columns}
+  loading={tableProps.loading}
+  sortModel={tableProps.sortModel}
+  onSortModelChange={tableProps.setSortModel}
+/>
+```
+
+---
+
+#### useFilterItems
+
+**File:** `useFilterItems.ts` (~166 LOC)
+
+**Purpose:** Manages filter state for data tables.
+
+```typescript
+interface UseFilterItemsReturn {
+  filterItems: FilterItem[];
+  setFilterItems: (items: FilterItem[]) => void;
+  addFilter: () => void;
+  removeFilter: (id: string) => void;
+  updateFilter: (id: string, fields: Partial<FilterFields>) => void;
+  resetFilters: () => void;
+  generateFilterRequest: () => string;
+  filterRequest: FilterRequest;
+}
+```
+
+**Usage:**
+```typescript
+const filters: Filter[] = [
+  { title: 'name', label: 'Name' },
+  { title: 'status', label: 'Status', type: 'enum', options: ['active', 'inactive'] },
+  { title: 'created_at', label: 'Created', date: true },
+];
+
+const { filterItems, addFilter, generateFilterRequest } = useFilterItems(filters);
+
+// Add filter
+addFilter();
+
+// Generate query string
+const queryString = generateFilterRequest(); // "&name=john&statusRange=active"
+```
+
+---
+
+#### useCSVHandling
+
+**File:** `useCSVHandling.ts` (~141 LOC)
+
+**Purpose:** CSV upload and download operations.
+
+```typescript
+interface UseCSVHandlingReturn {
+  csvFile: File | null;
+  setCsvFile: (file: File | null) => void;
+  isModalActive: boolean;
+  setIsModalActive: (active: boolean) => void;
+  isUploading: boolean;
+  isDownloading: boolean;
+  downloadCSV: () => Promise<void>;
+  uploadCSV: () => Promise<void>;
+  error: string | null;
+}
+```
+
+---
+
+### 5. Form Hooks
+
+Hooks for form management in edit pages.
+
+#### useEditPageSync
+
+**File:** `useEditPageSync.ts` (~166 LOC)
+
+**Purpose:** Syncs edit page forms with Redux entity state.
+
+```typescript
+interface UseEditPageSyncOptions<T> {
+  entitySelector: (state: RootState) => unknown;
+  fetchAction: AsyncThunk<unknown, { id?: string; query?: string }, object>;
+  initialValues: T;
+  postProcess?: (entity: T, initial: T) => T;
+  idOverride?: string;
+}
+
+interface UseEditPageSyncReturn<T> {
+  values: T;
+  setValues: React.Dispatch<React.SetStateAction<T>>;
+  id: string | null;
+  isLoading: boolean;
+  isFound: boolean;
+}
+```
+
+**Usage:**
+```typescript
+const initVals = { name: '', permissions: [] };
+
+const { values, id, isLoading } = useEditPageSync({
+  entitySelector: (state) => state.roles.roles,
+  fetchAction: fetch,
+  initialValues: initVals,
+  postProcess: (entity, initial) => ({
+    ...entity,
+    permissions: entity.permissions?.map(p => ({ value: p.id, label: p.name })) || [],
+  }),
+});
+
+// Use in Formik
+<Formik enableReinitialize initialValues={values} onSubmit={handleSubmit}>
+```
+
+---
+
+#### useFormSync
+
+**File:** `useFormSync.ts` (~108 LOC)
+
+**Purpose:** Generic form state management with field tracking.
+
+```typescript
+interface UseFormSyncReturn<T> {
+  values: T;
+  setFieldValue: (field: keyof T, value: T[keyof T]) => void;
+  setValues: (values: Partial<T>) => void;
+  resetForm: () => void;
+  isDirty: boolean;
+  dirtyFields: Set<keyof T>;
+}
+```
+
+---
+
+### 6. UI Utility Hooks
+
+General-purpose utility hooks.
+
+#### useDraggable
+
+**File:** `useDraggable.ts` (~200 LOC)
+
+**Purpose:** Generic draggable panel management with pointer tracking.
+
+```typescript
+interface UseDraggableResult {
+  position: Position;
+  setPosition: (position: Position) => void;
+  isDragging: boolean;
+  onDragStart: (event: React.MouseEvent) => void;
+  onDragStartIgnoreButtons: (event: React.MouseEvent) => void;
+}
+```
+
+**Usage:**
+```typescript
+const { position, onDragStart, isDragging } = useDraggable({
+  initialPosition: { x: 20, y: 20 },
+  elementWidth: 400,
+  elementHeight: 300,
+});
+
+<div style={{ left: position.x, top: position.y }}>
+  <div onMouseDown={onDragStart}>Drag Handle</div>
+  <div>Content</div>
+</div>
+```
+
+---
+
+#### useOutsideClick
+
+**File:** `useOutsideClick.ts` (~88 LOC)
+
+**Purpose:** Detects clicks outside specified elements.
+
+```typescript
+useOutsideClick({
+  containerRef: panelRef,
+  ignoreRefs: [buttonRef],
+  ignoreDataAttribute: 'data-element-id',
+  selectedValue: selectedElementId,
+  onOutsideClick: () => setSelectedId(''),
+  enabled: !!selectedId,
+});
+```
+
+---
+
+#### useElementEffects
+
+**File:** `useElementEffects.ts` (~128 LOC)
+
+**Purpose:** Manages element interactive effects (hover, focus, active) at runtime. Exposes internal state for integration with other hooks (e.g., `useAudioEffects`).
+
+```typescript
+interface UseElementEffectsResult {
+  effectStyle: CSSProperties;
+  eventHandlers: {
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    onFocus: () => void;
+    onBlur: () => void;
+    onMouseDown: () => void;
+    onMouseUp: () => void;
+    onTouchStart: () => void;
+    onTouchEnd: () => void;
+  };
+  onPersistClick: () => void;
+  /** Exposed state for audio effects integration */
+  state: {
+    isHovered: boolean;
+    isActive: boolean;
+  };
+}
+```
+
+**Priority:** active > focus > hover > base
+
+**Usage:**
+```typescript
+const { effectStyle, eventHandlers, state: effectState } = useElementEffects(element);
+
+// Use effectState for audio integration
+useAudioEffects({
+  isHovered: effectState.isHovered,
+  isActive: effectState.isActive,
+  // ...
+});
+
+<div style={{ ...baseStyle, ...effectStyle }} {...eventHandlers}>
+  {content}
+</div>
+```
+
+---
+
+#### useAudioEffects
+
+**File:** `useAudioEffects.ts` (~305 LOC)
+
+**Purpose:** Manages audio playback for element hover and click effects. Uses HTML5 Audio API for lightweight, non-visual audio playback with authenticated URL support.
+
+```typescript
+interface UseAudioEffectsOptions {
+  /** URL of audio to play on hover */
+  hoverAudioUrl?: string;
+  /** URL of audio to play on click/active */
+  clickAudioUrl?: string;
+  /** Volume level 0-1 (iOS ignores this) */
+  volume?: number;
+  /** Current hover state from useElementEffects */
+  isHovered: boolean;
+  /** Current active/pressed state from useElementEffects */
+  isActive: boolean;
+  /** Optional URL resolver for preloaded blob URLs */
+  resolveUrl?: (url: string | undefined) => string;
+  /** Reset key to stop audio (e.g., element ID or page slug) */
+  resetKey?: string | number;
+}
+
+interface UseAudioEffectsResult {
+  /** Manually trigger click audio playback */
+  playClickAudio: () => void;
+  /** Stop all audio playback */
+  stopAll: () => void;
+}
+```
+
+**Key Features:**
+- **Hover audio**: Plays to completion once started (not interrupted by mouse leave)
+- **Click audio**: Interruptible - clicking again restarts from beginning
+- **Authenticated URLs**: Fetches audio via `fetch()` with credentials, creates blob URLs
+- **Caching**: Tracks fetched URLs to prevent duplicate requests
+- **Mobile support**: Touch events (via `useElementEffects`) trigger hover audio
+
+**Cross-Browser Compatibility:**
+
+| Feature | Chrome | Firefox | Safari | iOS Safari | Android |
+|---------|--------|---------|--------|------------|---------|
+| HTML5 Audio | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Volume control | ✅ | ✅ | ✅ | ❌ (iOS ignores) | ✅ |
+| Autoplay (click) | ✅ | ✅ | ✅ | ✅ (after tap) | ✅ |
+
+**Usage:**
+```typescript
+// In CanvasElement.tsx or RuntimeElement.tsx
+const { effectStyle, eventHandlers, state: effectState } = useElementEffects(
+  isEditMode ? {} : effectProperties,
+);
+
+// Audio effects - only active in preview mode (not edit mode)
+useAudioEffects({
+  hoverAudioUrl: isEditMode ? undefined : effectProperties.hoverAudioUrl,
+  clickAudioUrl: isEditMode ? undefined : effectProperties.clickAudioUrl,
+  volume: parseFloat(effectProperties.audioVolume || '1'),
+  isHovered: effectState.isHovered,
+  isActive: effectState.isActive,
+  resolveUrl,  // Resolves to preloaded blob URLs
+  resetKey: element.id,
+});
+```
+
+**Integration with Element Effects:**
+The hook depends on `useElementEffects` for hover/active state. The `isHovered` and `isActive` states are passed through to trigger audio playback at the right moments.
+
+**Constructor vs Runtime:**
+- **Constructor Edit Mode**: Audio disabled (`hoverAudioUrl: undefined`)
+- **Constructor Preview Mode**: Audio enabled (press F5 to test)
+- **Runtime Presentation**: Audio enabled
+
+---
+
+#### useDashboardCounts
+
+**File:** `useDashboardCounts.ts` (~308 LOC)
+
+**Purpose:** Fetches entity counts for dashboard with permission filtering.
+
+```typescript
+interface UseDashboardCountsReturn {
+  counts: Record<string, EntityCountValue>;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+  getCount: (key: string) => EntityCountValue;
+  getVisibleEntities: () => EntityConfig[];
+}
+```
+
+**Dashboard Entities:**
+- users, roles, permissions, projects
+- project_memberships, assets, asset_variants
+- presigned_url_requests, tour_pages, project_audio_tracks
+- publish_events, pwa_caches, access_logs
+
+---
+
+#### useProjectAssets
+
+**File:** `useProjectAssets.ts` (~95 LOC)
+
+**Purpose:** Preloads and resolves project assets (favicon, og_image, logo) to presigned URLs. Handles both `storage_key` (relative paths) and legacy `cdn_url` (full S3 URLs) formats.
+
+```typescript
+interface ProjectAssetInput {
+  favicon_url?: string;
+  og_image_url?: string;
+  logo_url?: string;
+}
+
+interface ProjectAssets {
+  faviconUrl: string | null;
+  ogImageUrl: string | null;
+  logoUrl: string | null;
+  isLoading: boolean;
+}
+
+function useProjectAssets(project: ProjectAssetInput | null): ProjectAssets;
+```
+
+**Key Features:**
+- Extracts storage paths from URLs (handles both formats)
+- Queues presigned URL requests for relative paths
+- Resolves to playback URLs (presigned if available, otherwise proxy)
+- Tracks URL changes to avoid redundant processing
+
+**Usage:**
+```typescript
+const { faviconUrl, ogImageUrl, logoUrl, isLoading } = useProjectAssets(project);
+
+// Use resolved URLs
+{faviconUrl && <link rel="icon" href={faviconUrl} />}
+{ogImageUrl && <meta property="og:image" content={ogImageUrl} />}
+{logoUrl && <img src={logoUrl} alt="Logo" />}
+```
+
+---
+
+#### usePublishStatus
+
+**File:** `usePublishStatus.ts` (~113 LOC)
+
+**Purpose:** Fetches the last successful publish/save events for a project to display timestamps in the UI. Follows the `useDashboardCounts` pattern with `mountedRef` and parallel API calls.
+
+```typescript
+interface UsePublishStatusOptions {
+  projectId: string | null;
+}
+
+interface UsePublishStatusResult {
+  /** Last successful dev → stage save timestamp */
+  lastSavedToStage: string | null;
+  /** Last successful stage → production publish timestamp */
+  lastPublishedToProduction: string | null;
+  /** Whether data is loading */
+  isLoading: boolean;
+  /** Refresh the status (call after new publish) */
+  refresh: () => Promise<void>;
+}
+```
+
+**Key Features:**
+- Fetches both dev→stage and stage→production events in parallel via `Promise.all`
+- Uses `mountedRef` pattern to prevent state updates after unmount
+- Queries `publish_events` API with `projectId`, environment filters, and `status: 'success'`
+- Returns `finished_at` timestamp of most recent successful event
+
+**Usage:**
+```typescript
+// In Project Dashboard (pages/projects/[projectsId].tsx)
+const { lastPublishedToProduction, refresh: refreshPublishStatus } = usePublishStatus({
+  projectId,
+});
+
+// Display in button subtitle
+<BaseButton
+  label="Publish to Production"
+  subtitle={lastPublishedToProduction
+    ? `Last: ${dataFormatter.relativeTimestamp(lastPublishedToProduction)}`
+    : undefined}
+  onClick={() => setIsPublishModalActive(true)}
+/>
+
+// Refresh after successful publish
+const handlePublish = async () => {
+  await axios.post('/publish', { projectId, title, description });
+  await refreshPublishStatus();
+};
+
+// In Constructor (pages/constructor.tsx)
+const { lastSavedToStage, refresh: refreshPublishStatus } = usePublishStatus({
+  projectId,
+});
+
+// Project-level save timestamp: most recent updatedAt across all pages
+const lastProjectSaveAt = useMemo(() => {
+  if (!pages.length) return null;
+  return pages.reduce((latest, page) => {
+    if (!page.updatedAt) return latest;
+    if (!latest) return page.updatedAt;
+    return new Date(page.updatedAt) > new Date(latest) ? page.updatedAt : latest;
+  }, null as string | null);
+}, [pages]);
+
+// Wrap saveToStage to refresh status
+const handleSaveToStage = useCallback(async () => {
+  await saveToStage();
+  await refreshPublishStatus();
+}, [saveToStage, refreshPublishStatus]);
+
+// Pass timestamps to ConstructorMenu
+<ConstructorMenu
+  lastSavedAt={lastProjectSaveAt}  // Project-level, not page-level
+  lastSavedToStageAt={lastSavedToStage}
+  onSaveToStage={handleSaveToStage}
+/>
+```
+
+**Integration with dataFormatter:**
+```typescript
+import dataFormatter from '../../helpers/dataFormatter';
+
+// Format timestamp for display
+dataFormatter.relativeTimestamp(lastPublishedToProduction);
+// → "Just now", "5 min ago", "2 hours ago", "Today at 14:30", "Apr 28 at 16:45"
+```
+
+---
+
+## Index Exports
+
+**File:** `index.ts` (~44 LOC)
+
+The index file exports hooks and their types for tree-shaking friendly imports:
+
+```typescript
+// Exported from index.ts (centralized)
+export { useFilterItems } from './useFilterItems';
+export { useCSVHandling } from './useCSVHandling';
+export { useFormSync } from './useFormSync';
+export { useEntityTable } from './useEntityTable';
+export { useTransitionPlayback } from './useTransitionPlayback';
+export type { ReverseMode, TransitionConfig, UseTransitionPlaybackOptions,
+              PlaybackPhase, UseTransitionPlaybackResult } from './useTransitionPlayback';
+export { usePageNavigation } from './usePageNavigation';
+export type { NavigablePage, UsePageNavigationOptions,
+              UsePageNavigationResult } from './usePageNavigation';
+export { usePageNavigationState } from './usePageNavigationState';
+export type { NavigationPhase, UsePageNavigationStateOptions,
+              UsePageNavigationStateResult } from './usePageNavigationState';
+export { useBackgroundVideoPlayback } from './useBackgroundVideoPlayback';
+export type { UseBackgroundVideoPlaybackOptions,
+              UseBackgroundVideoPlaybackResult } from './useBackgroundVideoPlayback';
+export { useVideoSoundControl } from './useVideoSoundControl';
+export type { UseVideoSoundControlOptions,
+              UseVideoSoundControlResult } from './useVideoSoundControl';
+export { usePageDataLoader } from './usePageDataLoader';
+export type { UsePageDataLoaderOptions, UsePageDataLoaderResult } from './usePageDataLoader';
+
+// Import directly for better tree-shaking (not in index.ts)
+// - usePreloadOrchestrator
+// - useNeighborGraph
+// - useConstructorElements
+// - useCanvasElementDrag
+// - useTransitionPreview
+// - useOfflineMode
+// - useOutsideClick
+// - useCanvasElapsedTime
+// - useDraggable
+// - useMediaDurationProbe
+// - useIconPreload
+// - useProjectAssets
+```
+
+---
+
+## Design Patterns
+
+### 1. Options/Result Pattern
+
+All hooks follow a consistent interface pattern:
+
+```typescript
+interface UseXxxOptions {
+  // Configuration inputs
+}
+
+interface UseXxxResult {
+  // State and methods
+}
+
+function useXxx(options: UseXxxOptions): UseXxxResult {
+  // Implementation
+}
+```
+
+### 2. Callback Refs
+
+Heavy operations use callback refs to avoid re-renders:
+
+```typescript
+const readyBlobUrlsRef = useRef<Map<string, string>>(new Map());
+
+// O(1) lookup without triggering re-renders
+const getBlobUrl = useCallback((url: string) => {
+  return readyBlobUrlsRef.current.get(url) || null;
+}, []);
+```
+
+### 3. Cleanup on Unmount
+
+All hooks properly cleanup resources:
+
+```typescript
+useEffect(() => {
+  const controller = new AbortController();
+
+  fetchData(controller.signal);
+
+  return () => controller.abort();
+}, []);
+```
+
+### 4. Memoization
+
+Expensive computations are memoized:
+
+```typescript
+const neighbors = useMemo(() => {
+  return buildNeighborGraph(pages, pageLinks);
+}, [pages, pageLinks]);
+```
+
+---
+
+## Hook Composition
+
+Hooks are designed for composition - larger hooks use smaller hooks:
+
+```
+RuntimePresentation
+├── usePageDataLoader
+├── usePreloadOrchestrator
+│   └── useNeighborGraph
+├── usePageNavigationState     # Unified state machine (replaces 6 hooks)
+│   └── Internal: useReducer + derived state via useMemo
+├── useTransitionPlayback      # Uses pre-generated reversed videos
+└── usePageNavigation          # History tracking
+```
+
+```
+ConstructorPage
+├── usePageDataLoader
+├── usePreloadOrchestrator
+│   └── useNeighborGraph
+├── usePageNavigationState     # Same unified state machine
+├── useConstructorElements
+├── useCanvasElementDrag
+├── useConstructorPageActions
+├── useTransitionPreview
+├── useDraggable (multiple instances)
+└── useOutsideClick
+```
+
+**Note:** The `usePageNavigationState` hook consolidated:
+- `usePageSwitch` - URL resolution and switching
+- `useBackgroundState` - Background ready tracking
+- `useBackgroundTransition` - Fade-from-black effects
+- `useTransitionCleanup` - Video cleanup coordination
+- `useBackgroundUrls` - URL resolution for display
+- `pageLoadingUtils` - Loading state computation
+
+---
+
+## Performance Considerations
+
+### 1. Tree-Shaking
+
+Large hooks are imported directly rather than via index.ts:
+
+```typescript
+// Good - only imports what's needed
+import { usePreloadOrchestrator } from '../hooks/usePreloadOrchestrator';
+
+// Avoid for large hooks
+import { usePreloadOrchestrator } from '../hooks';
+```
+
+### 2. Ref-Based State
+
+State that doesn't need to trigger re-renders uses refs:
+
+```typescript
+// Good - no re-renders
+const queueRef = useRef<PriorityQueue>(new PriorityQueue());
+
+// Avoid for high-frequency updates
+const [queue, setQueue] = useState<Item[]>([]);
+```
+
+### 3. Debounced Updates
+
+High-frequency operations are debounced:
+
+```typescript
+const debouncedUpdate = useMemo(
+  () => debounce((value) => setPosition(value), 16),
+  []
+);
+```
+
+---
+
+## Testing Considerations
+
+Hooks can be tested with `@testing-library/react-hooks`:
+
+```typescript
+import { renderHook, act } from '@testing-library/react-hooks';
+import { useFilterItems } from './useFilterItems';
+
+test('adds filter', () => {
+  const { result } = renderHook(() => useFilterItems(filters));
+
+  act(() => {
+    result.current.addFilter();
+  });
+
+  expect(result.current.filterItems).toHaveLength(1);
+});
+```
+
+---
+
+## Component-Specific Hooks
+
+Some hooks are co-located with their components rather than in the central hooks directory:
+
+### useAssetUploader
+
+**Location:** `frontend/src/components/Assets/useAssetUploader.ts` (~279 LOC)
+
+**Purpose:** Batch asset upload management with queue tracking, concurrent uploads, and MIME validation.
+
+```typescript
+interface UseAssetUploaderReturn {
+  uploadingSections: string[];                    // Sections with active uploads
+  uploadQueues: Record<string, UploadQueueItem[]>; // Per-section upload queues
+  runBatchUpload: (section: AssetSection, files: File[]) => Promise<void>;
+}
+```
+
+**Key Features:**
+- Batch upload with queue management (max 2 concurrent)
+- Per-file progress tracking
+- Abortable uploads via AbortController
+- MIME validation via validation schema
+- Media duration probing for video/audio
+
+**Validation Integration:**
+```typescript
+// Passes validation schema to UploadService
+const validationSchema = { assetType: section.assetFormat };
+const remoteFile = await FileUploader.uploadChunked(
+  `assets/${projectId}`,
+  file,
+  validationSchema,  // Validates MIME type matches asset format
+  { onProgress, onStatus, signal }
+);
+```
+
+See [Asset Upload & Variants](../../documentation/asset-upload-variants.md) for complete upload flow documentation.
+
+---
+
+## Related Documentation
+
+- [Video Hooks Module](./video-hooks-module.md) - Video playback primitive hooks
+- [Constructor Page Editor](./constructor-page-editor.md) - Visual tour builder
+- [Runtime Presentation](./runtime-presentation.md) - Tour playback viewer
+- [Navigation & Smooth Transitions](./navigation-smooth-transitions.md) - Page switching with transitions
+- [Frontend Architecture](./frontend-architecture.md) - Overall frontend structure
+- [Components Module](./components-module.md) - React components
+- [Assets Preloading](../../documentation/assets-preloading.md) - Preloading strategy
+- [Asset Upload & Variants](../../documentation/asset-upload-variants.md) - Asset upload pipeline
+
+---
+
+## Summary
+
+| Category | Hooks | Total LOC | Notes |
+|----------|-------|-----------|-------|
+| Runtime/Preloading | 10 | ~3,274 | Includes `usePageNavigationState` (~520 LOC) |
+| Video Hooks (new) | 8 | ~1,270 | New composable video primitives |
+| PWA/Offline | 5 | ~1,160 | Unchanged |
+| Constructor | 10 | ~2,156 | Uses shared `usePageNavigationState` |
+| Table/List | 3 | ~595 | Unchanged |
+| Form | 2 | ~274 | Unchanged |
+| UI Utility | 10 | ~1,583 | +useAudioEffects (~305 LOC) |
+| Query Hooks | 13 | ~1,051 | Unchanged |
+| **Total** | **53** | **~10,843** | +8 video hooks, -4 consolidated, +1 audio hook |
+
+**Recent Architecture Changes:**
+
+1. **Page Navigation Consolidation:** 6+ fragmented hooks consolidated into `usePageNavigationState`:
+   - Replaced boolean flag combinations with explicit phases
+   - Prevented race conditions via atomic `useReducer` transitions
+   - Eliminated ~1,100 LOC of duplicated state management
+
+2. **Video Hooks Module:** New `hooks/video/` directory with 8 primitive hooks:
+   - Composable primitives for any video playback scenario
+   - Used by `useTransitionPlayback`, `useBackgroundVideoPlayback`, `useVideoPlayer`
+   - See [Video Hooks Module](./video-hooks-module.md) for details
+
+3. **Preloading Simplification:** Stream-first approach:
+   - Removed neighbor graph traversal (`useNeighborGraph` deleted)
+   - Only preloads current page + outgoing transition videos
+   - Videos stream on-demand, then cache for replay
+
+4. **Flash Fix:** Instant overlay hide with rAF delay:
+   - `TransitionPreviewOverlay` uses `requestAnimationFrame` delay before hiding
+   - Ensures new background is painted before overlay removed
+   - `PreviousBackgroundOverlay` simplified to pure show/hide (no fade)
+
+5. **Audio Effects:** New `useAudioEffects` hook for element sound effects:
+   - Plays audio on hover start (completes even after mouse leave)
+   - Plays audio on click/active (interruptible, restarts on re-click)
+   - Uses authenticated fetch with blob URLs for secure audio access
+   - Integrates with `useElementEffects` via exposed `state.isHovered`/`state.isActive`
+   - Works in constructor preview mode and runtime presentations
+
+The hooks module provides comprehensive reusable logic that powers the application's core features while maintaining clean separation of concerns and tree-shaking friendly architecture.
diff --git a/frontend/docs/hooks-reference.md b/frontend/docs/hooks-reference.md
new file mode 100644
index 0000000..ee96c61
--- /dev/null
+++ b/frontend/docs/hooks-reference.md
@@ -0,0 +1,2683 @@
+# Frontend Hooks Reference
+
+Complete documentation for all custom React hooks in the Tour Builder Platform frontend.
+
+---
+
+## Navigation
+
+### Quick Links
+
+| Category | Hooks |
+|----------|-------|
+| [Redux Integration](#redux-integration-hooks) | [useAppDispatch & useAppSelector](#useappdispatch--useappselector) |
+| [Data Management](#data-management-hooks) | [useFormSync](#useformsync) · [useEditPageSync](#useeditpagesync) · [useDashboardCounts](#usedashboardcounts) · [useEntityTable](#useentitytable) · [useCSVHandling](#usecsvhandling) · [useFilterItems](#usefilteritems) · [useElementSettingsForm](#useelementsettingsform) |
+| [Offline & Caching](#offline--caching-hooks) | [useOfflineMode](#useofflinemode) · [useStorageQuota](#usestoragequota) |
+| [Preloading](#preloading-hooks) | [usePreloadOrchestrator](#usepreloadorchestrator) · [useNeighborGraph](#useneighborgraph) · [useNetworkAware](#usenetworkaware) · [usePWAPreload](#usepwapreload) · [usePreloadProgress](#usepreloadprogress) |
+| [Media Playback](#media-playback-hooks) | [useReversePlayback](#usereverseplayback) · [useTransitionPlayback](#usetransitionplayback) · [useBackgroundTransition](#usebackgroundtransition) · [usePageDataLoader](#usepagedataloader) · [useElementEffects](#useelementeffects) |
+| [Navigation](#navigation-hooks) | [usePageSwitch](#usepageswitch) · [usePageNavigation](#usepagenavigation) |
+| [Asset Upload](#asset-upload-hooks) | [useAssetUploader](#useassetuploader) |
+| [Constructor](#constructor-hooks) | [useConstructorElements](#useconstructorelements) · [useConstructorPageActions](#useconstructorpageactions) · [useTransitionPreview](#usetransitionpreview) · [useCanvasElapsedTime](#usecanvaselapsedtime) · [useCanvasElementDrag](#usecanvaselementdrag) · [useIconPreload](#useiconpreload) · [useMediaDurationProbe](#usemediadurationprobe) |
+| [Utility](#utility-hooks) | [useDevCompilationStatus](#usedevcompilationstatus) · [useOutsideClick](#useoutsideclick) · [useDraggable](#usedraggable) |
+
+### All Hooks (A-Z)
+
+| Hook | Category | Used By | Description |
+|------|----------|---------|-------------|
+| [useAppDispatch](#useappdispatch--useappselector) | Redux | All | Type-safe Redux dispatch |
+| [useAppSelector](#useappdispatch--useappselector) | Redux | All | Type-safe Redux state selection |
+| [useAssetUploader](#useassetuploader) | Upload | Constructor | Batch asset uploads with progress |
+| [useBackgroundTransition](#usebackgroundtransition) | Media | Runtime, Constructor | Background fade transition effects |
+| [useCanvasElapsedTime](#usecanvaselapsedtime) | Constructor | Constructor | Elapsed time for element visibility |
+| [useCanvasElementDrag](#usecanvaselementdrag) | Constructor | Constructor | Element drag with % positioning |
+| [useConstructorElements](#useconstructorelements) | Constructor | Constructor | Element CRUD operations |
+| [useConstructorPageActions](#useconstructorpageactions) | Constructor | Constructor | Page save/create/publish |
+| [useCSVHandling](#usecsvhandling) | Data | List Pages | CSV import/export |
+| [useDashboardCounts](#usedashboardcounts) | Data | Dashboard | Dashboard entity counts |
+| [useDevCompilationStatus](#usedevcompilationstatus) | Utility | _app | Next.js dev compilation status |
+| [useDraggable](#usedraggable) | Utility | Constructor | Draggable panel management |
+| [useEditPageSync](#useeditpagesync) | Data | Edit Pages | Edit page data sync |
+| [useElementEffects](#useelementeffects) | Media | Runtime | Element hover/focus/active effects |
+| [useElementSettingsForm](#useelementsettingsform) | Data | Constructor | Element settings form state |
+| [useEntityTable](#useentitytable) | Data | Table Pages | Complete table management |
+| [useFilterItems](#usefilteritems) | Data | List Pages | Filter state management |
+| [useFormSync](#useformsync) | Data | Edit Pages | Form sync with Redux entities |
+| [useIconPreload](#useiconpreload) | Constructor | Constructor | Icon image preloading |
+| [useMediaDurationProbe](#usemediadurationprobe) | Constructor | Constructor | Media duration probing |
+| [useNeighborGraph](#useneighborgraph) | Preload | (internal) | Navigation graph building |
+| [useNetworkAware](#usenetworkaware) | Preload | (internal) | Network condition monitoring |
+| [useOfflineMode](#useofflinemode) | Offline | OfflineToggle | Project offline download |
+| [useOutsideClick](#useoutsideclick) | Utility | Constructor | Click outside detection |
+| [usePageDataLoader](#usepagedataloader) | Media | Runtime, Constructor | Project/page data loading |
+| [usePageNavigation](#usepagenavigation) | Navigation | Runtime, Constructor | Page state with history |
+| [usePageSwitch](#usepageswitch) | Navigation | Runtime, Constructor | Smooth page switching |
+| [usePreloadOrchestrator](#usepreloadorchestrator) | Preload | Runtime, Constructor | Asset preload with blob URLs |
+| [usePreloadProgress](#usepreloadprogress) | Preload | OfflineToggle | Preload job tracking |
+| [usePWAPreload](#usepwapreload) | Preload | OfflineToggle | PWA asset caching |
+| [useReversePlayback](#usereverseplayback) | Media | (internal) | Reverse video playback |
+| [useStorageQuota](#usestoragequota) | Offline | OfflineToggle | Storage quota monitoring |
+| [useTransitionPlayback](#usetransitionplayback) | Media | Runtime, Constructor | Transition video management |
+| [useTransitionPreview](#usetransitionpreview) | Constructor | Constructor | Transition video preview |
+
+**Legend:** Runtime = `RuntimePresentation.tsx`, Constructor = `constructor.tsx`, (internal) = used by other hooks
+
+### Presentation Components Hook Usage
+
+**RuntimePresentation.tsx** (public tour viewer):
+```
+usePageDataLoader ──→ usePreloadOrchestrator ──→ usePageSwitch
+                              │
+                              ▼
+                    useTransitionPlayback ──→ useBackgroundTransition
+```
+
+**constructor.tsx** (tour editor):
+```
+usePageDataLoader ──→ usePreloadOrchestrator ──→ usePageSwitch
+        │                     │
+        ▼                     ▼
+useConstructorElements   useTransitionPlayback ──→ useBackgroundTransition
+        │                     │
+        ▼                     ▼
+useConstructorPageActions useTransitionPreview
+        │
+        ▼
+useCanvasElementDrag, useCanvasElapsedTime, useIconPreload, useMediaDurationProbe
+```
+
+---
+
+## Overview
+
+The platform provides a comprehensive set of custom hooks organized into categories:
+
+- **Redux Integration** - Type-safe store access
+- **Data Management** - Form sync, table management, CSV handling
+- **Offline & Caching** - PWA offline mode, storage quota
+- **Preloading** - Asset preloading, neighbor graph, network awareness
+- **Media Playback** - Video transitions, reverse playback
+- **Navigation** - Page navigation with history
+- **Asset Upload** - Batch upload with progress tracking
+- **Constructor** - Element management, page actions, transitions, dragging
+- **Utility** - Outside click detection, draggable panels
+
+**Important: Blob URL Rendering**
+
+Preloading hooks (`usePreloadOrchestrator`, `usePageSwitch`) return blob URLs for cached assets. When rendering these URLs as images, use native `<img>` tags instead of Next.js `<Image>`:
+
+- **Next.js Image re-fetches on every render** - even with `unoptimized` prop
+- **Blob URLs don't benefit from optimization** - already in-memory
+- **Use conditional rendering**: native `<img>` for `blob:` URLs, Next.js Image for regular URLs
+
+See `usePageSwitch` documentation for implementation example.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         Frontend Hooks Architecture                          │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                         Redux Layer                                     │ │
+│  │                                                                         │ │
+│  │   useAppDispatch ←──────────────────────────────→ useAppSelector       │ │
+│  │         │                                               │               │ │
+│  │         ▼                                               ▼               │ │
+│  │   ┌─────────────┐                               ┌─────────────┐        │ │
+│  │   │ Entity      │                               │ Entity      │        │ │
+│  │   │ Slices      │                               │ State       │        │ │
+│  │   └─────────────┘                               └─────────────┘        │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+│                                    │                                         │
+│                    ┌───────────────┼───────────────┐                        │
+│                    ▼               ▼               ▼                        │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
+│  │   useFormSync    │  │  useEntityTable  │  │  useCSVHandling  │          │
+│  │                  │  │                  │  │                  │          │
+│  │  Form ↔ Entity   │  │  Table + CRUD    │  │  Import/Export   │          │
+│  └──────────────────┘  └──────────────────┘  └──────────────────┘          │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                      Offline & Preload Layer                           │ │
+│  │                                                                         │ │
+│  │   useOfflineMode ──→ useStorageQuota                                   │ │
+│  │         │                                                               │ │
+│  │         ▼                                                               │ │
+│  │   usePreloadOrchestrator ──→ useNeighborGraph                          │ │
+│  │         │    (getReadyBlobUrl)     │                                    │ │
+│  │         │                          ▼                                    │ │
+│  │         ├──→ useNetworkAware    usePWAPreload                          │ │
+│  │         ▼                                                               │ │
+│  │   usePageSwitch (blob URL resolution + transitions)                    │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                         Media Layer                                     │ │
+│  │                                                                         │ │
+│  │   useTransitionPlayback ──→ useReversePlayback                         │ │
+│  │         │                                                               │ │
+│  │         ▼                                                               │ │
+│  │   useBackgroundTransition ──→ usePageDataLoader                        │ │
+│  │                                                                         │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                     Constructor Layer                                   │ │
+│  │                                                                         │ │
+│  │   useConstructorElements ──→ useConstructorPageActions                 │ │
+│  │         │                            │                                  │ │
+│  │         ▼                            ▼                                  │ │
+│  │   useCanvasElementDrag        useTransitionPreview                     │ │
+│  │         │                            │                                  │ │
+│  │         ▼                            ▼                                  │ │
+│  │   useCanvasElapsedTime    useIconPreload, useMediaDurationProbe        │ │
+│  │                                                                         │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+│                                                                              │
+│  ┌────────────────────────────────────────────────────────────────────────┐ │
+│  │                       Utility Layer                                     │ │
+│  │                                                                         │ │
+│  │   useDraggable ──→ useOutsideClick ──→ useElementEffects               │ │
+│  │                                                                         │ │
+│  └────────────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Redux Integration Hooks
+
+### useAppDispatch & useAppSelector
+
+**Source:** `frontend/src/stores/hooks.ts`
+
+Type-safe Redux hooks for accessing store and dispatching actions.
+
+```typescript
+import { useDispatch, useSelector } from 'react-redux';
+import type { TypedUseSelectorHook } from 'react-redux';
+import type { RootState, AppDispatch } from './store';
+
+export const useAppDispatch: () => AppDispatch = useDispatch;
+export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;
+```
+
+**Usage:**
+
+```typescript
+import { useAppDispatch, useAppSelector } from '../stores/hooks';
+import { fetch, update } from '../stores/users/usersSlice';
+
+function UserList() {
+  const dispatch = useAppDispatch();
+  const users = useAppSelector((state) => state.users.users);
+  const loading = useAppSelector((state) => state.users.loading);
+
+  useEffect(() => {
+    dispatch(fetch({ query: '?limit=100' }));
+  }, [dispatch]);
+
+  return loading ? <Spinner /> : <Table data={users} />;
+}
+```
+
+**Benefits:**
+- Full TypeScript support for state shape
+- Autocomplete for state paths
+- Type-checked dispatch payloads
+
+---
+
+## Data Management Hooks
+
+### useFormSync
+
+**Source:** `frontend/src/hooks/useFormSync.ts`
+
+Synchronizes form state with Redux entity data, eliminating boilerplate in edit pages.
+
+**Signature:**
+
+```typescript
+function useFormSync<T extends BaseEntity, TFormValues extends Record<string, unknown>>(
+  options: UseFormSyncOptions<T, TFormValues>
+): UseFormSyncReturn<TFormValues>
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| entitySelector | `(state: RootState) => T \| T[] \| undefined` | Redux state selector |
+| fetchAction | `AsyncThunk` | Thunk to fetch entity |
+| initialValues | `TFormValues` | Default form values |
+| transformEntity | `(entity: T) => TFormValues` | Optional field mapper |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| formValues | `TFormValues` | Current form state |
+| setFormValues | `(values: TFormValues) => void` | Update form |
+| isLoading | `boolean` | Fetch in progress |
+| entityId | `string \| undefined` | ID from router |
+| resetForm | `() => void` | Reset to initial values |
+
+**Example:**
+
+```typescript
+const { formValues, setFormValues, isLoading, entityId } = useFormSync({
+  entitySelector: (state) => state.projects.projects,
+  fetchAction: fetchProjects,
+  initialValues: {
+    name: '',
+    slug: '',
+    description: '',
+  },
+  transformEntity: (project) => ({
+    name: project.name,
+    slug: project.slug,
+    description: project.description || '',
+  }),
+});
+
+// In Formik
+<Formik
+  initialValues={formValues}
+  enableReinitialize
+  onSubmit={handleSubmit}
+>
+  {/* form fields */}
+</Formik>
+```
+
+**Key Features:**
+- Extracts entity ID from Next.js router query
+- Handles both single entity and array state shapes
+- Auto-fetches when ID is available
+- Optional transform for field name mapping
+
+---
+
+### useEditPageSync
+
+**Source:** `frontend/src/hooks/useEditPageSync.ts`
+
+Simplified hook for edit pages that syncs form state with Redux entity data. Reduces ~50 lines of boilerplate code per edit page.
+
+**Signature:**
+
+```typescript
+function useEditPageSync<T extends Record<string, unknown>>(
+  options: UseEditPageSyncOptions<T>
+): UseEditPageSyncReturn<T>
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| entitySelector | `(state: RootState) => unknown` | Redux selector for entity |
+| fetchAction | `AsyncThunk` | Thunk to fetch entity |
+| initialValues | `T` | Default form values |
+| postProcess | `(entity: T, initial: T) => T` | Optional post-processing |
+| idOverride | `string` | Optional ID override (defaults to router.query.id) |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| values | `T` | Current form values |
+| setValues | `React.Dispatch<SetStateAction<T>>` | Update form values |
+| id | `string \| null` | Entity ID from router |
+| isLoading | `boolean` | Fetch in progress |
+| isFound | `boolean` | Entity was found |
+
+**Example:**
+
+```typescript
+const initVals = { name: '', permissions: [] };
+
+const EditRolesPage = () => {
+  const { values, id, isLoading } = useEditPageSync({
+    entitySelector: (state) => state.roles.roles,
+    fetchAction: fetch,
+    initialValues: initVals,
+  });
+
+  const handleSubmit = async (data) => {
+    await dispatch(update({ id, data }));
+    router.push('/roles/roles-list');
+  };
+
+  return (
+    <Formik enableReinitialize initialValues={values} onSubmit={handleSubmit}>
+      ...
+    </Formik>
+  );
+};
+```
+
+**Simplified Variant:**
+
+```typescript
+// Returns [values, setValues] tuple for drop-in replacement
+const [initialValues, setInitialValues] = useEditPageSyncSimple({
+  entitySelector: (state) => state.roles.roles,
+  fetchAction: fetch,
+  initialValues: initVals,
+});
+```
+
+---
+
+### useDashboardCounts
+
+**Source:** `frontend/src/hooks/useDashboardCounts.ts`
+
+Fetches entity counts for the dashboard with permission-based filtering. Uses `Promise.allSettled` for resilience.
+
+**Signature:**
+
+```typescript
+function useDashboardCounts(currentUser: User | null): UseDashboardCountsReturn
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| counts | `Record<string, number \| string \| null>` | Entity counts |
+| loading | `boolean` | Fetch in progress |
+| error | `Error \| null` | Error if failed |
+| refetch | `() => Promise<void>` | Manual refetch |
+| getCount | `(key: string) => EntityCountValue` | Get count for entity |
+| getVisibleEntities | `() => EntityConfig[]` | Get permitted entities |
+
+**Example:**
+
+```typescript
+const { counts, loading, getVisibleEntities, getCount } = useDashboardCounts(currentUser);
+
+const entities = getVisibleEntities();
+const userCount = getCount('users'); // number | 'Loading...' | null
+
+return (
+  <DashboardCards>
+    {entities.map((entity) => (
+      <Card key={entity.key} count={getCount(entity.key)} />
+    ))}
+  </DashboardCards>
+);
+```
+
+**Entity Configuration:** Uses `DASHBOARD_ENTITIES` constant with 13 entities (users, roles, permissions, projects, etc.), each with permission requirements.
+
+---
+
+### useEntityTable
+
+**Source:** `frontend/src/hooks/useEntityTable.ts`
+
+Complete table state management including pagination, sorting, filtering, selection, and CRUD.
+
+**Signature:**
+
+```typescript
+function useEntityTable<T extends BaseEntity>(
+  options: UseEntityTableOptions<T>
+): UseEntityTableReturn<T>
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| entityName | `string` | Entity identifier |
+| sliceSelector | `(state: RootState) => EntitySliceState<T>` | Redux slice selector |
+| fetchAction | `AsyncThunk` | Fetch thunk |
+| updateAction | `AsyncThunk` | Update thunk (optional) |
+| deleteAction | `AsyncThunk` | Delete single item thunk |
+| deleteByIdsAction | `AsyncThunk` | Batch delete thunk (optional) |
+| setRefetchAction | `(value: boolean) => Action` | Trigger refetch |
+| loadColumnsFunction | `Function` | Column config loader |
+| filters | `Filter[]` | Available filters |
+| perPage | `number` | Items per page (default: 10) |
+
+**Returns:**
+
+```typescript
+interface UseEntityTableReturn<T> {
+  // Data
+  data: T[];
+  columns: GridColDef[];
+  loading: boolean;
+  count: number;
+
+  // Pagination
+  currentPage: number;
+  setCurrentPage: (page: number) => void;
+  numPages: number;
+
+  // Sorting
+  sortModel: GridSortModel;
+  setSortModel: (model: GridSortModel) => void;
+
+  // Selection
+  selectedRows: string[];
+  setSelectedRows: (ids: string[]) => void;
+
+  // Filters
+  filterItems: FilterItem[];
+  setFilterItems: (items: FilterItem[]) => void;
+  filterRequest: string;
+  handleFilterSubmit: () => void;
+  handleFilterReset: () => void;
+
+  // Delete operations
+  isDeleteModalActive: boolean;
+  deleteTargetId: string | null;
+  handleDeleteClick: (id: string) => void;
+  handleDeleteConfirm: () => Promise<void>;
+  handleDeleteCancel: () => void;
+  handleDeleteSelected: () => Promise<void>;
+
+  // Table operations
+  handleRowUpdate: (id: string, data: Partial<T>) => Promise<void>;
+  loadData: (page?: number, request?: string) => void;
+}
+```
+
+**Example:**
+
+```typescript
+const {
+  data,
+  columns,
+  loading,
+  currentPage,
+  setCurrentPage,
+  numPages,
+  sortModel,
+  setSortModel,
+  filterItems,
+  setFilterItems,
+  handleFilterSubmit,
+  handleDeleteConfirm,
+  isDeleteModalActive,
+} = useEntityTable({
+  entityName: 'assets',
+  sliceSelector: (state) => state.assets,
+  fetchAction: fetchAssets,
+  deleteAction: deleteAsset,
+  deleteByIdsAction: deleteAssetsByIds,
+  setRefetchAction: setRefetch,
+  loadColumnsFunction: configureAssetsCols,
+  filters: assetFilters,
+  perPage: 25,
+});
+
+return (
+  <>
+    <FilterBar
+      filters={filters}
+      filterItems={filterItems}
+      setFilterItems={setFilterItems}
+      onSubmit={handleFilterSubmit}
+    />
+    <DataGrid
+      rows={data}
+      columns={columns}
+      loading={loading}
+      sortModel={sortModel}
+      onSortModelChange={setSortModel}
+      paginationModel={{ page: currentPage, pageSize: 25 }}
+      onPaginationModelChange={({ page }) => setCurrentPage(page)}
+      rowCount={count}
+    />
+    <DeleteModal
+      isActive={isDeleteModalActive}
+      onConfirm={handleDeleteConfirm}
+      onCancel={handleDeleteCancel}
+    />
+  </>
+);
+```
+
+---
+
+### useCSVHandling
+
+**Source:** `frontend/src/hooks/useCSVHandling.ts`
+
+Manages CSV import and export operations for bulk data handling.
+
+**Signature:**
+
+```typescript
+function useCSVHandling(options: UseCSVHandlingOptions): UseCSVHandlingReturn
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| endpoint | `string` | API endpoint (e.g., 'users') |
+| uploadAction | `AsyncThunk` | CSV upload thunk |
+| setRefetchAction | `(value: boolean) => Action` | Trigger data reload |
+| fileName | `string` | Export filename (optional) |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| csvFile | `File \| null` | Selected file |
+| setCsvFile | `(file: File \| null) => void` | Set file |
+| isModalActive | `boolean` | Import modal visible |
+| setIsModalActive | `(active: boolean) => void` | Toggle modal |
+| isUploading | `boolean` | Upload in progress |
+| isDownloading | `boolean` | Download in progress |
+| downloadCSV | `() => Promise<void>` | Trigger export |
+| uploadCSV | `() => Promise<void>` | Trigger import |
+| error | `string \| null` | Error message |
+
+**Example:**
+
+```typescript
+const {
+  csvFile,
+  setCsvFile,
+  isUploading,
+  isDownloading,
+  downloadCSV,
+  uploadCSV,
+  error,
+} = useCSVHandling({
+  endpoint: 'users',
+  uploadAction: uploadUsersCsv,
+  setRefetchAction: setRefetch,
+  fileName: 'users-export.csv',
+});
+
+return (
+  <>
+    <Button onClick={downloadCSV} disabled={isDownloading}>
+      Export CSV
+    </Button>
+    <input
+      type="file"
+      accept=".csv"
+      onChange={(e) => setCsvFile(e.target.files?.[0] || null)}
+    />
+    <Button onClick={uploadCSV} disabled={isUploading || !csvFile}>
+      Import CSV
+    </Button>
+    {error && <Alert severity="error">{error}</Alert>}
+  </>
+);
+```
+
+---
+
+### useFilterItems
+
+**Source:** `frontend/src/hooks/useFilterItems.ts`
+
+Manages filter state for data tables with support for range and enum filters.
+
+**Signature:**
+
+```typescript
+function useFilterItems(filters: Filter[]): UseFilterItemsReturn
+```
+
+**Filter Definition:**
+
+```typescript
+interface Filter {
+  title: string;      // Field name
+  label: string;      // Display label
+  number?: boolean;   // Range filter (numbers)
+  date?: boolean;     // Range filter (dates)
+  type?: 'enum';      // Enum filter
+  options?: string[]; // Enum options
+}
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| filterItems | `FilterItem[]` | Active filters |
+| setFilterItems | `(items: FilterItem[]) => void` | Replace filters |
+| addFilter | `() => void` | Add new filter row |
+| removeFilter | `(id: string) => void` | Remove filter |
+| updateFilter | `(id: string, fields: Partial<FilterFields>) => void` | Update filter |
+| resetFilters | `() => void` | Clear all filters |
+| generateFilterRequest | `() => string` | Build query string |
+| filterRequest | `FilterRequest` | Filter object |
+
+**Example:**
+
+```typescript
+const filters: Filter[] = [
+  { title: 'name', label: 'Name' },
+  { title: 'created_at', label: 'Created', date: true },
+  { title: 'environment', label: 'Environment', type: 'enum', options: ['dev', 'stage', 'production'] },
+];
+
+const {
+  filterItems,
+  addFilter,
+  removeFilter,
+  updateFilter,
+  generateFilterRequest,
+  resetFilters,
+} = useFilterItems(filters);
+
+// Generate query: "&name=test&created_atRange=2024-01-01&created_atRange=2024-12-31"
+const queryString = generateFilterRequest();
+```
+
+---
+
+### useElementSettingsForm
+
+**Source:** `frontend/src/components/ElementSettings/useElementSettingsForm.ts`
+
+Form state management hook for element settings across global defaults, project defaults, and constructor pages.
+
+**Signature:**
+
+```typescript
+function useElementSettingsForm(
+  options: UseElementSettingsFormOptions
+): UseElementSettingsFormReturn
+
+interface UseElementSettingsFormOptions {
+  elementType: CanvasElementType | string;
+}
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| state | `FormState` | Current form state (all settings) |
+| setField | `(field, value) => void` | Update single field |
+| setFields | `(updates) => void` | Update multiple fields |
+| applySettings | `(json) => void` | Load settings from JSON |
+| getStyleValues | `() => ElementStyleProperties` | Get CSS style values |
+| buildSettingsJson | `() => Record<string, unknown>` | Serialize to JSON for saving |
+| isNavigationType | `boolean` | Element is navigation_next/prev |
+| isTooltipType | `boolean` | Element is tooltip |
+| isDescriptionType | `boolean` | Element is description |
+| isGalleryType | `boolean` | Element is gallery |
+| isCarouselType | `boolean` | Element is carousel |
+| isMediaType | `boolean` | Element is video/audio player |
+| addGalleryCard | `() => void` | Add gallery card |
+| removeGalleryCard | `(id) => void` | Remove gallery card |
+| updateGalleryCard | `(id, field, value) => void` | Update gallery card |
+| addCarouselSlide | `() => void` | Add carousel slide |
+| removeCarouselSlide | `(id) => void` | Remove carousel slide |
+| updateCarouselSlide | `(id, field, value) => void` | Update carousel slide |
+
+**FormState includes:**
+- Common: label, xPercent, yPercent, appearDelaySec, appearDurationSec
+- CSS: width, height, margin, padding, fontSize, border, borderRadius, opacity, etc.
+- Navigation: iconUrl, navLabel, navType, targetPageSlug, transitionVideoUrl, etc.
+- Tooltip: tooltipTitle, tooltipText
+- Description: descriptionTitle, descriptionText, typography settings
+- Media: mediaUrl, mediaAutoplay, mediaLoop, mediaMuted
+- Gallery: galleryCards array
+- Carousel: carouselSlides array, prev/next icons
+
+**Example:**
+
+```typescript
+const form = useElementSettingsForm({ elementType: 'navigation_next' });
+
+// Load existing settings
+useEffect(() => {
+  if (item?.settings_json) {
+    form.applySettings(item.settings_json);
+  }
+}, [item]);
+
+// Update field
+form.setField('navLabel', 'Next Page');
+
+// Save
+const handleSave = async () => {
+  const settings = form.buildSettingsJson();
+  await axios.put(`/project-element-defaults/${id}`, {
+    data: { settings_json: settings },
+  });
+};
+
+// Render type-specific sections
+{form.isNavigationType && (
+  <NavigationSettingsSection
+    navLabel={form.state.navLabel}
+    onChange={(field, value) => form.setField(field, value)}
+  />
+)}
+```
+
+**Key Features:**
+- Type-aware: Shows/hides fields based on element type
+- Bidirectional: `applySettings()` loads JSON, `buildSettingsJson()` serializes
+- Validation: Clamps position to 0-100, normalizes CSS units
+- Array management: Gallery cards and carousel slides with add/remove/update
+
+---
+
+## Offline & Caching Hooks
+
+### useOfflineMode
+
+**Source:** `frontend/src/hooks/useOfflineMode.ts`
+
+Manages offline mode state and project download functionality with progress tracking.
+
+**Signature:**
+
+```typescript
+function useOfflineMode(options: UseOfflineModeOptions): UseOfflineModeResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| projectId | `string \| null` | Project to download |
+| projectSlug | `string` | Project slug (optional) |
+| projectName | `string` | Display name (optional) |
+| enabled | `boolean` | Enable hook (default: true) |
+
+**Returns:**
+
+```typescript
+interface UseOfflineModeResult {
+  // Status
+  isOfflineCapable: boolean;    // Browser supports offline
+  isDownloaded: boolean;        // Project fully cached
+  isDownloading: boolean;       // Download in progress
+  status: ProjectOfflineStatus; // 'not_downloaded' | 'downloading' | 'downloaded' | 'error' | 'outdated'
+  progress: number;             // 0-100
+  downloadedAssets: number;
+  totalAssets: number;
+  downloadedBytes: number;
+  totalBytes: number;
+  error: string | null;
+
+  // Actions
+  startDownload: () => Promise<void>;
+  pauseDownload: () => void;
+  resumeDownload: () => void;
+  cancelDownload: () => void;
+  deleteOfflineData: () => Promise<void>;
+  checkForUpdates: () => Promise<boolean>;
+
+  // Info
+  projectInfo: OfflineProject | null;
+  estimatedSize: number;
+  formatSize: (bytes: number) => string;
+}
+```
+
+**Example:**
+
+```typescript
+const {
+  isOfflineCapable,
+  status,
+  progress,
+  downloadedAssets,
+  totalAssets,
+  startDownload,
+  deleteOfflineData,
+  formatSize,
+  downloadedBytes,
+} = useOfflineMode({
+  projectId: project?.id,
+  projectSlug: project?.slug,
+  enabled: true,
+});
+
+return (
+  <div>
+    {status === 'not_downloaded' && (
+      <Button onClick={startDownload}>
+        Download for Offline ({formatSize(estimatedSize)})
+      </Button>
+    )}
+    {status === 'downloading' && (
+      <ProgressBar value={progress}>
+        {downloadedAssets}/{totalAssets} assets
+      </ProgressBar>
+    )}
+    {status === 'downloaded' && (
+      <Button onClick={deleteOfflineData}>Remove Offline Data</Button>
+    )}
+  </div>
+);
+```
+
+**Key Features:**
+- Checks Service Worker and Cache API support
+- Uses frontend asset discovery (same as online preload) - no backend manifest
+- Requires `pages` prop for asset discovery
+- Priority-based downloads (images: 100, videos: 50, audio: 75)
+- Progress via IndexedDB and DownloadEventBus
+- Storage quota validation before download
+- Handles partial → full download upgrades for offline completeness
+
+---
+
+### useStorageQuota
+
+**Source:** `frontend/src/hooks/useStorageQuota.ts`
+
+Monitors storage quota and usage for offline assets.
+
+**Signature:**
+
+```typescript
+function useStorageQuota(): UseStorageQuotaResult
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| usage | `number` | Bytes used |
+| quota | `number \| Infinity` | Total available |
+| percentUsed | `number` | Usage percentage |
+| available | `number` | Bytes remaining |
+| isLoading | `boolean` | Fetching quota |
+| error | `string \| null` | Error message |
+| refresh | `() => Promise<void>` | Manual refresh |
+| requestPersistence | `() => Promise<boolean>` | Request persistent storage |
+| isPersisted | `boolean` | Storage is persistent |
+| isWarning | `boolean` | >= 80% used |
+| isCritical | `boolean` | >= 95% used |
+| formatSize | `(bytes: number) => string` | Format bytes |
+| canStore | `(bytes: number) => boolean` | Check if fits |
+
+**Example:**
+
+```typescript
+const {
+  usage,
+  quota,
+  percentUsed,
+  isWarning,
+  isCritical,
+  formatSize,
+  requestPersistence,
+  isPersisted,
+} = useStorageQuota();
+
+return (
+  <StorageIndicator>
+    <span>{formatSize(usage)} / {formatSize(quota)}</span>
+    {isWarning && <WarningIcon />}
+    {isCritical && <CriticalIcon />}
+    {!isPersisted && (
+      <Button onClick={requestPersistence}>
+        Enable Persistent Storage
+      </Button>
+    )}
+  </StorageIndicator>
+);
+```
+
+---
+
+## Preloading Hooks
+
+### usePreloadOrchestrator
+
+**Source:** `frontend/src/hooks/usePreloadOrchestrator.ts`
+
+**Used by:** `RuntimePresentation.tsx`, `constructor.tsx`
+
+Main coordinator for online mode asset preloading with priority queue management. Downloads assets from S3 presigned URLs, stores in Cache API/IndexedDB, and provides instant blob URL lookup for smooth page transitions.
+
+**Signature:**
+
+```typescript
+function usePreloadOrchestrator(
+  options: UsePreloadOrchestratorOptions
+): UsePreloadOrchestratorResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| pages | `PreloadPage[]` | All pages (filtered by environment) |
+| pageLinks | `PreloadPageLink[]` | Navigation links (from `extractPageLinksAndElements`) |
+| elements | `PreloadElement[]` | Page elements |
+| currentPageId | `string \| null` | Active page |
+| pageHistory | `string[]` | Navigation history |
+| enabled | `boolean` | Enable preloading (default: true) |
+| maxNeighborDepth | `number` | BFS depth limit (default: 1, immediate neighbors only) |
+
+**Environment Isolation:** Pages, pageLinks, and elements should be filtered by environment (`dev`, `stage`, `production`) before passing to this hook. This prevents preloading assets from other environments.
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| isPreloading | `boolean` | Downloads active |
+| preloadedUrls | `Set<string>` | Cached URLs |
+| queueLength | `number` | Pending downloads |
+| preloadAsset | `(url: string, priority?: number) => void` | Manual preload |
+| clearQueue | `() => void` | Cancel pending |
+| getCachedBlobUrl | `(url: string) => Promise<string \| null>` | Get cached blob (creates new blob URL) |
+| isUrlPreloaded | `(url: string) => Promise<boolean>` | Check cache |
+| getReadyBlobUrl | `(url: string) => string \| null` | Instant lookup - decoded blob URL (O(1)) |
+
+**Example:**
+
+```typescript
+const {
+  isPreloading,
+  preloadedUrls,
+  getCachedBlobUrl,
+  getReadyBlobUrl,
+  preloadAsset,
+} = usePreloadOrchestrator({
+  pages,
+  pageLinks,
+  elements,
+  currentPageId,
+  enabled: !isOffline,
+});
+
+// Instant blob URL lookup (O(1), already decoded, ready to display)
+const readyUrl = getReadyBlobUrl(videoUrl);
+if (readyUrl) {
+  videoRef.current.src = readyUrl;
+}
+
+// Fallback: async cached blob (creates new blob URL, may need decode)
+const blobUrl = await getCachedBlobUrl(videoUrl);
+videoRef.current.src = blobUrl || videoUrl;
+
+// Manual high-priority preload
+preloadAsset('https://example.com/important.mp4', 200);
+```
+
+**S3 Presigned URL Flow with Storage Key Mapping:**
+```
+1. POST /api/file/presign { urls: [asset1, asset2, ...] }  // Max 50 per batch
+2. Download from presigned URLs (1-hour expiry)
+3. Store in Cache API (keyed by both download URL and storage key)
+4. Create blob URL: URL.createObjectURL(blob)
+5. Decode if image
+6. Store in readyBlobUrlsRef Map:
+   - keyed by download URL (presigned URL)
+   - keyed by storage key (canonical path, e.g., "assets/project-123/video.mp4")
+   - keyed by proxy URL (for fallback compatibility)
+```
+
+**Storage Key Mapping:**
+The orchestrator maps downloaded blobs to multiple keys for reliable cache hits:
+| Key Type | Example | Purpose |
+|----------|---------|---------|
+| Download URL | `https://s3...?X-Amz-Signature=ABC` | Original presigned URL |
+| Storage Key | `assets/project-123/video.mp4` | Canonical path (most reliable) |
+| Proxy URL | `/api/file/download?privateUrl=...` | Fallback compatibility |
+
+This ensures lookups succeed regardless of which URL is used, since presigned URL signatures change on each resolution but the storage key remains constant.
+
+---
+
+### useNeighborGraph
+
+**Source:** `frontend/src/hooks/useNeighborGraph.ts`
+
+Builds navigation graph from page links to determine which pages are neighbors and should have their assets preloaded.
+
+**Signature:**
+
+```typescript
+function useNeighborGraph(options: UseNeighborGraphOptions): NeighborGraphResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| pages | `PreloadPage[]` | All pages (should be filtered by environment first) |
+| pageLinks | `PreloadPageLink[]` | Navigation links with `from_pageId` and `to_pageId` |
+| elements | `PreloadElement[]` | Page elements (for asset extraction) |
+| maxDepth | `number` | BFS depth (default: 1, immediate neighbors only) |
+
+**Note:** Page links are extracted from `ui_schema_json` navigation elements using `extractPageLinksAndElements()` and passed as `PreloadPageLink[]` with resolved page IDs.
+
+**Environment Filtering:** Pages and elements should be filtered by environment (`dev`, `stage`, or `production`) before passing to this hook to ensure preloading respects environment isolation.
+
+**Returns:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| getNeighbors | `(pageId: string, depth?: number) => PreloadNeighborInfo[]` | Get neighbor pages |
+| getAssetsForPages | `(pageIds: string[]) => PreloadAssetInfo[]` | Get page assets |
+| getPrioritizedAssets | `(pageId: string, depth?: number) => PreloadAssetInfo[]` | Prioritized assets |
+| adjacencyList | `Map<string, string[]>` | Raw graph (debugging) |
+
+**Example:**
+
+```typescript
+const { getNeighbors, getPrioritizedAssets } = useNeighborGraph({
+  pages,
+  pageLinks,  // Links with from_pageId, to_pageId
+  elements,   // Elements with content_json for asset extraction
+  maxDepth: 1,
+});
+
+// Get neighbors within 1 hop
+const neighbors = getNeighbors(currentPageId);
+// Returns: [{pageId: 'page-2', distance: 1}]
+
+// Get prioritized assets for preloading
+const assets = getPrioritizedAssets(currentPageId);
+// Sorted by priority: current page (1000) > neighbor (100/distance) + type bonus
+```
+
+---
+
+### useNetworkAware
+
+**Source:** `frontend/src/hooks/useNetworkAware.ts`
+
+Monitors network conditions and adapts preloading strategy.
+
+**Signature:**
+
+```typescript
+function useNetworkAware(): UseNetworkAwareResult
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| networkInfo | `NetworkInfo` | Connection details |
+| shouldPreloadAggressively | `boolean` | Good connection |
+| preferLowQuality | `boolean` | Slow connection |
+| recommendedConcurrency | `number` | Parallel downloads |
+| suggestOfflineMode | `boolean` | Very slow connection |
+
+**NetworkInfo:**
+
+```typescript
+interface NetworkInfo {
+  isOnline: boolean;
+  effectiveType: 'slow-2g' | '2g' | '3g' | '4g' | undefined;
+  downlink: number | undefined;     // Mbps
+  rtt: number | undefined;          // Round-trip time ms
+  saveData: boolean;
+}
+```
+
+**Example:**
+
+```typescript
+const {
+  networkInfo,
+  shouldPreloadAggressively,
+  recommendedConcurrency,
+  preferLowQuality,
+  suggestOfflineMode,
+} = useNetworkAware();
+
+// Adapt preloading
+const concurrency = recommendedConcurrency; // 1 for 2g, 2 for 3g, 3 for 4g
+
+// Show offline suggestion
+if (suggestOfflineMode) {
+  showToast('Connection is slow. Consider downloading for offline use.');
+}
+
+// Select asset quality
+const videoUrl = preferLowQuality ? video.lowRes : video.highRes;
+```
+
+---
+
+### usePWAPreload
+
+**Source:** `frontend/src/hooks/usePWAPreload.ts`
+
+PWA asset preloading with progress tracking.
+
+**Signature:**
+
+```typescript
+function usePWAPreload(options: UsePWAPreloadOptions): PreloadState
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| assets | `AssetToPreload[]` | Assets to preload |
+| onComplete | `() => void` | Completion callback |
+| onError | `(errors: string[]) => void` | Error callback |
+| skipIfCached | `boolean` | Skip if already cached (default: true) |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| isPreloading | `boolean` | In progress |
+| progress | `number` | 0-100 |
+| loadedCount | `number` | Completed assets |
+| totalCount | `number` | Total assets |
+| errors | `string[]` | Failed URLs |
+| startPreload | `() => Promise<void>` | Manual trigger |
+| isCached | `boolean` | All cached |
+
+**Example:**
+
+```typescript
+const { isPreloading, progress, loadedCount, totalCount, startPreload } = usePWAPreload({
+  assets: [
+    { url: '/images/bg.jpg', type: 'image' },
+    { url: '/videos/intro.mp4', type: 'video' },
+  ],
+  onComplete: () => setShowOverlay(false),
+  skipIfCached: true,
+});
+
+return isPreloading ? (
+  <LoadingOverlay>
+    Loading {loadedCount}/{totalCount} ({Math.round(progress)}%)
+  </LoadingOverlay>
+) : null;
+```
+
+---
+
+### usePreloadProgress
+
+**Source:** `frontend/src/hooks/usePreloadProgress.ts`
+
+Tracks preload job progress via DownloadEventBus with auto-cleanup.
+
+**Signature:**
+
+```typescript
+function usePreloadProgress(): UsePreloadProgressResult
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| jobs | `PreloadJob[]` | All tracked jobs |
+| activeCount | `number` | Downloading/queued jobs |
+| completedCount | `number` | Completed jobs |
+| errorCount | `number` | Failed jobs |
+| totalProgress | `number` | Overall progress 0-100 |
+| isActive | `boolean` | Any active downloads |
+| clearJob | `(id: string) => void` | Remove specific job |
+| clearAllCompleted | `() => void` | Clear completed jobs |
+| clearAllErrors | `() => void` | Clear errored jobs |
+
+**PreloadJob:**
+
+```typescript
+interface PreloadJob {
+  id: string;
+  assetId: string;
+  url: string;
+  filename: string;
+  progress: number;
+  status: 'queued' | 'downloading' | 'completed' | 'error';
+  bytesLoaded: number;
+  totalBytes: number;
+  addedAt: number;
+  startedAt?: number;
+  completedAt?: number;
+  error?: string;
+}
+```
+
+**Example:**
+
+```typescript
+const {
+  jobs,
+  activeCount,
+  totalProgress,
+  isActive,
+  clearAllCompleted,
+} = usePreloadProgress();
+
+return isActive ? (
+  <PreloadIndicator>
+    <span>{activeCount} downloads in progress ({totalProgress}%)</span>
+    {jobs.map((job) => (
+      <JobProgress key={job.id} job={job} />
+    ))}
+  </PreloadIndicator>
+) : null;
+```
+
+**Key Features:**
+- Listens to DownloadEventBus for preload events
+- Auto-removes completed jobs after configurable delay
+- Auto-removes error jobs after longer delay
+- Byte-based progress calculation when available
+
+---
+
+## Media Playback Hooks
+
+### useReversePlayback
+
+**Source:** `frontend/src/hooks/useReversePlayback.ts`
+
+Handles reverse video playback with fallback strategies.
+
+**Signature:**
+
+```typescript
+function useReversePlayback(options: UseReversePlaybackOptions): UseReversePlaybackResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| videoRef | `RefObject<HTMLVideoElement>` | Video element ref |
+| onComplete | `() => void` | Completion callback |
+| preloadedUrls | `Set<string>` | Cached URLs (optional) |
+| videoUrl | `string` | Current video URL (optional) |
+| getCachedBlobUrl | `(url: string) => Promise<string \| null>` | Blob URL getter (optional) |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| startReverse | `() => Promise<void>` | Start reverse playback |
+| stopReverse | `() => void` | Stop playback |
+| isReversing | `boolean` | Playback active |
+| isBuffering | `boolean` | Buffering video |
+| canUseNativeReverse | `boolean` | Browser supports native reverse |
+
+**Example:**
+
+```typescript
+const videoRef = useRef<HTMLVideoElement>(null);
+
+const { startReverse, stopReverse, isReversing, isBuffering } = useReversePlayback({
+  videoRef,
+  onComplete: () => navigateBack(),
+  getCachedBlobUrl,
+});
+
+// Trigger reverse when back button clicked
+const handleBack = async () => {
+  await startReverse();
+};
+
+return (
+  <div>
+    <video ref={videoRef} src={transitionUrl} />
+    {isBuffering && <Spinner />}
+  </div>
+);
+```
+
+**Playback Strategies:**
+1. **Native:** `playbackRate = -1` (modern browsers)
+2. **Frame-stepping:** Fallback seeking (15-30 FPS based on cache status)
+
+---
+
+### useTransitionPlayback
+
+**Source:** `frontend/src/hooks/useTransitionPlayback.ts`
+
+**Used by:** `RuntimePresentation.tsx`, `constructor.tsx`
+
+Manages complex transition video playback with forward/reverse support. Handles blob URL resolution from preload cache for smooth seeking during reverse playback.
+
+**Signature:**
+
+```typescript
+function useTransitionPlayback(
+  options: UseTransitionPlaybackOptions
+): UseTransitionPlaybackResult
+```
+
+**Parameters:**
+
+```typescript
+interface UseTransitionPlaybackOptions {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  transition: TransitionConfig | null;
+  onComplete: (targetPageId?: string) => void;
+  onError?: (reason: string) => void;
+
+  timeouts?: {
+    playbackStartMs?: number;   // Default: 3000
+    durationBufferMs?: number;  // Default: 200
+    hardTimeoutMs?: number;     // Default: 45000
+  };
+
+  features?: {
+    useBlobUrl?: boolean;
+    preDecodeImages?: boolean;
+    getTargetPageImages?: () => string[];
+  };
+
+  preload?: {
+    preloadedUrls?: Set<string>;
+    getCachedBlobUrl?: (url: string) => Promise<string | null>;
+    getReadyBlobUrl?: (url: string) => string | null;  // Instant O(1) lookup
+  };
+}
+
+interface TransitionConfig {
+  videoUrl: string;           // Resolved URL (presigned or proxy) for playback
+  storageKey?: string;        // Raw storage path for cache lookup (e.g., "assets/project-123/video.mp4")
+  reverseMode: 'none' | 'reverse' | 'separate';
+  reverseVideoUrl?: string;   // For 'separate' mode
+  reverseStorageKey?: string; // Storage key for reverse video
+  durationSec?: number;
+  targetPageId?: string;      // Resolved from targetPageSlug at navigation time
+  displayName?: string;
+}
+```
+
+**Note:** Navigation elements store `targetPageSlug` in `ui_schema_json`. At navigation time, the slug is resolved to a page ID before being passed to this hook.
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| phase | `PlaybackPhase` | Current phase |
+| isBuffering | `boolean` | Loading video |
+| isReversing | `boolean` | Reverse playback |
+| cancel | `() => void` | Cancel transition |
+| forceComplete | `() => void` | Skip to end |
+
+**PlaybackPhase:** `'idle' | 'preparing' | 'playing' | 'reversing' | 'finishing' | 'completed'`
+
+**Example:**
+
+```typescript
+const videoRef = useRef<HTMLVideoElement>(null);
+
+const { phase, isBuffering, cancel } = useTransitionPlayback({
+  videoRef,
+  transition: {
+    videoUrl: resolveAssetPlaybackUrl(transitionPath),  // Resolved URL
+    storageKey: transitionPath,  // Raw storage path for cache lookup
+    reverseMode: 'reverse',
+    durationSec: 1.5,
+    targetPageId: 'page-gallery',
+  },
+  onComplete: (targetPageId) => {
+    setCurrentPage(targetPageId);
+  },
+  features: {
+    preDecodeImages: true,
+    getTargetPageImages: () => getPageImages(targetPageId),
+  },
+  preload: {
+    preloadedUrls: preloadOrchestrator.preloadedUrls,
+    getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+    getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,  // Instant lookup
+  },
+});
+
+return (
+  <TransitionOverlay visible={phase !== 'idle'}>
+    <video ref={videoRef} muted autoPlay playsInline />
+    {isBuffering && <LoadingIndicator />}
+    <Button onClick={cancel}>Skip</Button>
+  </TransitionOverlay>
+);
+```
+
+**Reverse Modes:**
+- `none`: Forward playback only
+- `reverse`: Play forward, then reverse same video
+- `separate`: Play forward video, then separate reverse video
+
+**Storage Key Lookup Priority:**
+The hook uses `storageKey` for reliable cache hits across presigned URL regeneration:
+1. `getReadyBlobUrl(storageKey)` - instant O(1) in-memory lookup
+2. `getCachedBlobUrl(storageKey)` - Cache API lookup (post-refresh)
+3. `getReadyBlobUrl(videoUrl)` - fallback by resolved URL
+4. `getCachedBlobUrl(videoUrl)` - fallback by resolved URL
+5. Network fetch - final fallback
+
+---
+
+### useBackgroundTransition
+
+**Source:** `frontend/src/hooks/useBackgroundTransition.ts`
+
+**Used by:** `RuntimePresentation.tsx`, `constructor.tsx`
+
+Manages background transition effects when switching pages. Handles fade-out animation of transition video overlay and coordinates with page switch hook.
+
+**Signature:**
+
+```typescript
+function useBackgroundTransition(
+  options: UseBackgroundTransitionOptions
+): UseBackgroundTransitionResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| pageSwitch | `PageSwitchInterface` | Page switch hook instance |
+| fadeOut | `FadeOutConfig` | Optional fade-out configuration |
+
+**FadeOutConfig (for RuntimePresentation):**
+
+```typescript
+interface FadeOutConfig {
+  pendingTransitionComplete: boolean;  // Video finished, waiting for bg ready
+  isBackgroundReady: boolean;          // New background loaded
+  transitionVideoRef: RefObject<HTMLVideoElement>;
+  onTransitionCleanup: () => void;
+}
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| isOverlayFadingOut | `boolean` | Overlay currently fading |
+| resetFadeOut | `() => void` | Reset fade state |
+
+**Example:**
+
+```typescript
+// Full mode with fade-out (RuntimePresentation)
+const { isOverlayFadingOut, resetFadeOut } = useBackgroundTransition({
+  pageSwitch,
+  fadeOut: {
+    pendingTransitionComplete,
+    isBackgroundReady,
+    transitionVideoRef,
+    onTransitionCleanup: () => {
+      setTransitionPreview(null);
+      setPendingTransitionComplete(false);
+    },
+  },
+});
+
+// Simple mode - direct navigation only (constructor)
+useBackgroundTransition({ pageSwitch });
+```
+
+**Modes:**
+- **Full mode** (RuntimePresentation): Fade-out animation + direct navigation clearing
+- **Simple mode** (constructor): Direct navigation clearing only
+
+---
+
+### usePageDataLoader
+
+**Source:** `frontend/src/hooks/usePageDataLoader.ts`
+
+**Used by:** `RuntimePresentation.tsx`, `constructor.tsx`
+
+Unified hook for loading project and page data in presentation components. Handles both public access (by slug) and authenticated access (by ID).
+
+**Signature:**
+
+```typescript
+function usePageDataLoader(
+  options: UsePageDataLoaderOptions
+): UsePageDataLoaderResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| projectId | `string` | Project ID (constructor mode) |
+| projectSlug | `string` | Project slug (runtime mode) |
+| environment | `'dev' \| 'stage' \| 'production'` | Environment filter |
+| enabled | `boolean` | Enable loading (default: true) |
+| apiHeaders | `Record<string, string>` | Custom API headers |
+| initialPageId | `string` | Initial page ID from route |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| project | `RuntimeProject \| null` | Loaded project |
+| pages | `RuntimePage[]` | Filtered and sorted pages |
+| isLoading | `boolean` | Loading in progress |
+| error | `string` | Error message |
+| reload | `(preservePageId?) => Promise<void>` | Reload data |
+| initialPageId | `string` | Selected initial page ID |
+
+**Example:**
+
+```typescript
+// Runtime mode (public presentation)
+const { project, pages, isLoading, error } = usePageDataLoader({
+  projectSlug: 'my-project',
+  environment: 'production',
+});
+
+// Constructor mode (authenticated)
+const { project, pages, isLoading, error, reload } = usePageDataLoader({
+  projectId: 'uuid-here',
+  environment: 'dev',
+  enabled: isAuthReady,
+});
+```
+
+**Features:**
+- Loads by slug (runtime) or ID (constructor)
+- Filters pages by environment
+- Sorts pages by sort_order
+- Handles authentication errors
+- Supports page preservation on reload
+
+---
+
+### useElementEffects
+
+**Source:** `frontend/src/hooks/useElementEffects.ts`
+
+Manages element interactive effects (hover, focus, active) at runtime. Since CSS pseudo-classes don't work with inline styles, this hook handles state-based style application via JavaScript events.
+
+**Signature:**
+
+```typescript
+function useElementEffects(
+  effects: Partial<ElementEffectProperties>
+): UseElementEffectsResult
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| effectStyle | `CSSProperties` | Style to merge with base element style |
+| eventHandlers | `object` | Event handlers for the element |
+
+**Event Handlers:**
+- `onMouseEnter`, `onMouseLeave` - Hover effects
+- `onFocus`, `onBlur` - Focus effects
+- `onMouseDown`, `onMouseUp` - Active/pressed effects
+
+**Example:**
+
+```typescript
+const { effectStyle, eventHandlers } = useElementEffects({
+  hoverScale: 1.1,
+  hoverOpacity: 0.8,
+  activeScale: 0.95,
+  transitionDuration: '0.2s',
+});
+
+return (
+  <button
+    style={{ ...baseStyle, ...effectStyle }}
+    {...eventHandlers}
+  >
+    {content}
+  </button>
+);
+```
+
+**Effect Priority:** active > focus > hover > base (highest wins)
+
+---
+
+## Navigation Hooks
+
+### usePageSwitch
+
+**Source:** `frontend/src/hooks/usePageSwitch.ts`
+
+**Used by:** `RuntimePresentation.tsx`, `constructor.tsx`
+
+Unified page switching hook that eliminates white flashes during page transitions by using preloaded blob URLs and keeping previous background visible until new one is ready.
+
+**Signature:**
+
+```typescript
+function usePageSwitch(options?: UsePageSwitchOptions): UsePageSwitchResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| preloadCache | `PreloadCacheProvider` | Optional preload cache provider |
+
+**PreloadCacheProvider Interface:**
+
+```typescript
+interface PreloadCacheProvider {
+  /** Instant lookup - returns decoded blob URL ready to display (O(1)) */
+  getReadyBlobUrl?: (url: string) => string | null;
+  /** Fallback: async blob URL from cache (creates new blob URL) */
+  getCachedBlobUrl?: (url: string) => Promise<string | null>;
+  preloadedUrls?: Set<string>;
+}
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| currentBgImageUrl | `string` | Current background image URL |
+| currentBgVideoUrl | `string` | Current background video URL |
+| currentBgAudioUrl | `string` | Current background audio URL |
+| previousBgImageUrl | `string` | Previous background for overlay |
+| isSwitching | `boolean` | Page switch in progress |
+| isNewBgReady | `boolean` | New background ready to display |
+| switchToPage | `(page, onSwitched?) => Promise<void>` | Switch to page with transition |
+| setBackgroundsDirectly | `(img, vid, aud) => void` | Direct set without transition |
+| markBackgroundReady | `() => void` | Mark background as loaded |
+| clearPreviousBackground | `() => void` | Clear overlay after fade |
+
+**Example:**
+
+```typescript
+const pageSwitch = usePageSwitch({
+  preloadCache: {
+    getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,  // Instant O(1) lookup
+    getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,  // Fallback
+    preloadedUrls: preloadOrchestrator.preloadedUrls,
+  },
+});
+
+// Switch to a page with smooth transition
+await pageSwitch.switchToPage(targetPage, () => {
+  setActivePageId(targetPage.id);
+});
+
+// In render - previous background overlay fades out
+{pageSwitch.previousBgImageUrl && (
+  <div
+    className='absolute inset-0 transition-opacity duration-200'
+    style={{
+      backgroundImage: `url("${pageSwitch.previousBgImageUrl}")`,
+      opacity: pageSwitch.isNewBgReady ? 0 : 1,
+    }}
+  />
+)}
+
+// Current background with onLoad handler
+<NextImage
+  src={pageSwitch.currentBgImageUrl}
+  onLoad={pageSwitch.markBackgroundReady}
+/>
+```
+
+**Key Features:**
+- Instant blob URL lookup via `getReadyBlobUrl()` (O(1), already decoded)
+- Fallback to `getCachedBlobUrl()` if ready URL not available
+- Presigned URL fallback with automatic retry via proxy on CORS failure
+- Keeps previous background visible until new one is painted
+- Double RAF (requestAnimationFrame) ensures browser has painted before fade
+- Automatic blob URL cleanup to prevent memory leaks
+
+**White Flash Prevention Strategy with Storage Key Priority:**
+1. Before switching, save current background as "previous"
+2. Try `getReadyBlobUrl(storagePath)` - instant O(1) lookup by storage key
+3. Try `getCachedBlobUrl(storagePath)` - Cache API lookup by storage key
+4. Resolve to playback URL and try `getReadyBlobUrl(resolvedUrl)`
+5. Try `getCachedBlobUrl(resolvedUrl)` by resolved URL
+6. Fallback: load with presigned URL (retries with proxy on CORS failure)
+7. Set new background and wait for Image onLoad
+8. Fade out previous background overlay after paint confirmed
+
+**Storage Key Lookup:**
+The hook prioritizes storage key lookups (e.g., `assets/project-123/bg.jpg`) over resolved URLs because:
+- Storage keys are canonical and don't change
+- Presigned URL signatures change on each resolution
+- Storage key mapping ensures cache hits across URL regenerations
+
+**Image Rendering for Blob URLs:**
+When rendering images from blob URLs, use native `<img>` tags instead of Next.js `<Image>`:
+```tsx
+// Background image example
+{backgroundImageUrl.startsWith('blob:') ? (
+  <img
+    src={backgroundImageUrl}
+    alt=""
+    className="absolute inset-0 w-full h-full object-cover"
+    onLoad={() => pageSwitch.markBackgroundReady()}
+  />
+) : (
+  <NextImage
+    src={backgroundImageUrl}
+    fill
+    sizes="100vw"
+    className="object-cover"
+    onLoad={() => pageSwitch.markBackgroundReady()}
+  />
+)}
+```
+
+**Why conditional rendering:**
+- Next.js Image re-fetches `src` on every component re-render
+- Pages with frequent state updates (e.g., 100ms timers) cause thousands of requests
+- Blob URLs are already in-memory and don't benefit from Next.js optimization
+- Native `<img>` with blob URLs is cached by browser and doesn't re-fetch
+
+---
+
+### usePageNavigation
+
+**Source:** `frontend/src/hooks/usePageNavigation.ts`
+
+Page navigation state with optional history tracking.
+
+**Signature:**
+
+```typescript
+function usePageNavigation<TPage extends NavigablePage>(
+  options: UsePageNavigationOptions<TPage>
+): UsePageNavigationResult<TPage>
+```
+
+**Parameters:**
+
+```typescript
+interface NavigablePage {
+  id: string;
+  sort_order?: number;
+  slug?: string;
+}
+
+interface UsePageNavigationOptions<TPage> {
+  pages: TPage[];
+  defaultPageId?: string;
+  trackHistory?: boolean;  // Default: true
+  onPageChange?: (pageId: string, isBack: boolean) => void;
+}
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| currentPageId | `string \| null` | Active page ID |
+| currentPage | `TPage \| null` | Active page object |
+| pageHistory | `string[]` | Navigation history |
+| previousPageId | `string \| null` | Previous page ID |
+| defaultPage | `TPage \| null` | Initial page |
+| setCurrentPageId | `(pageId: string) => void` | Navigate (no history) |
+| applyPageSelection | `(pageId: string, isBack?: boolean) => void` | Navigate with history |
+| isBackNavigation | `(pageId: string) => boolean` | Check if back nav |
+| goBack | `() => boolean` | Go to previous page |
+| resetHistory | `() => void` | Clear history |
+
+**Example - Runtime with History:**
+
+```typescript
+const nav = usePageNavigation({
+  pages,
+  trackHistory: true,
+  onPageChange: (pageId, isBack) => {
+    analytics.track('page_view', { pageId, isBack });
+  },
+});
+
+// Navigate forward
+nav.applyPageSelection('page-gallery');
+
+// Navigate back
+if (nav.previousPageId) {
+  nav.goBack();
+}
+
+// Check direction
+const transitionDirection = nav.isBackNavigation(targetPageId)
+  ? 'reverse'
+  : 'forward';
+```
+
+**Example - Editor without History:**
+
+```typescript
+const nav = usePageNavigation({
+  pages,
+  defaultPageId: firstPageId,
+  trackHistory: false,
+});
+
+// Simple navigation
+nav.setCurrentPageId('page-2');
+```
+
+---
+
+## Asset Upload Hooks
+
+### useAssetUploader
+
+**Source:** `frontend/src/components/Assets/useAssetUploader.ts`
+
+Batch asset uploads with concurrent workers and progress tracking.
+
+**Signature:**
+
+```typescript
+function useAssetUploader(options: UseAssetUploaderOptions): UseAssetUploaderReturn
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| selectedProjectId | `string` | Target project |
+| onUploadComplete | `() => void` | Completion callback |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| uploadingSections | `string[]` | Sections with active uploads |
+| uploadQueues | `Record<string, UploadQueueItem[]>` | Per-section queues |
+| runBatchUpload | `(section: AssetSection, files: File[]) => Promise<void>` | Start upload |
+
+**UploadQueueItem:**
+
+```typescript
+interface UploadQueueItem {
+  id: string;
+  fileName: string;
+  progress: number;  // 0-100
+  status: 'queued' | 'uploading' | 'saving' | 'success' | 'error';
+  error?: string;
+}
+```
+
+**Example:**
+
+```typescript
+const { uploadingSections, uploadQueues, runBatchUpload } = useAssetUploader({
+  selectedProjectId: project?.id,
+  onUploadComplete: () => {
+    toast.success('Upload complete!');
+    refreshAssets();
+  },
+});
+
+const handleFileSelect = (files: File[]) => {
+  runBatchUpload(
+    { key: 'images', label: 'Images', assetFormat: 'image', assetCategory: 'general' },
+    files
+  );
+};
+
+return (
+  <div>
+    <FileDropzone onDrop={handleFileSelect} />
+    {uploadQueues['images']?.map((item) => (
+      <UploadProgress key={item.id} item={item} />
+    ))}
+  </div>
+);
+```
+
+**Features:**
+- Max 2 concurrent uploads
+- 5 MB chunk size, 3 retries
+- Media duration probing (video/audio)
+- Automatic metadata submission
+
+---
+
+## Constructor Hooks
+
+Hooks specifically designed for the visual tour builder (constructor.tsx). These manage element CRUD, page actions, transitions, dragging, and timing.
+
+### useConstructorElements
+
+**Source:** `frontend/src/hooks/useConstructorElements.ts`
+
+Manages element CRUD operations with defaults merging. Core hook for element management in the constructor.
+
+**Signature:**
+
+```typescript
+function useConstructorElements(
+  options: UseConstructorElementsOptions
+): UseConstructorElementsResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| initialElements | `CanvasElement[]` | Starting elements |
+| elementDefaultsByType | `Record<CanvasElementType, Partial<CanvasElement>>` | Project defaults |
+| allowedNavigationTypes | `NavigationElementType[]` | Allowed nav types |
+| onElementsChange | `(elements) => void` | Change callback |
+| initialSelectedElementId | `string` | Initial selection from route |
+| onElementSelected | `(id) => void` | Selection callback |
+| onSelectionCleared | `() => void` | Clear selection callback |
+| onElementAdded | `(element) => void` | Add callback |
+| onElementRemoved | `(id) => void` | Remove callback |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| elements | `CanvasElement[]` | Current elements |
+| setElements | `Dispatch<SetStateAction>` | Set elements directly |
+| selectedElementId | `string` | Selected element ID |
+| selectedElement | `CanvasElement \| null` | Selected element |
+| selectElement | `(id) => void` | Select element |
+| clearSelection | `() => void` | Clear selection |
+| addElement | `(type) => void` | Add new element |
+| updateSelectedElement | `(patch) => void` | Update selected |
+| updateElement | `(id, patch) => void` | Update by ID |
+| removeSelectedElement | `() => void` | Remove selected |
+| removeElement | `(id) => void` | Remove by ID |
+| galleryCards | `{add, update, remove}` | Gallery operations |
+| carouselSlides | `{add, update, remove}` | Carousel operations |
+| updateElementPosition | `(id, x, y) => void` | Update position |
+| normalizeNavigationType | `(el, type) => CanvasElement` | Normalize nav type |
+
+**Example:**
+
+```typescript
+const {
+  elements,
+  selectedElement,
+  selectElement,
+  addElement,
+  updateSelectedElement,
+  removeSelectedElement,
+} = useConstructorElements({
+  initialElements: parsedElements,
+  elementDefaultsByType: projectDefaults,
+  allowedNavigationTypes: ['navigation_next', 'navigation_prev'],
+});
+
+// Add new element
+addElement('hotspot');
+
+// Update selected element
+updateSelectedElement({ label: 'New Label', xPercent: 50 });
+```
+
+---
+
+### useConstructorPageActions
+
+**Source:** `frontend/src/hooks/useConstructorPageActions.ts`
+
+Handles page create/save/publish operations in the constructor.
+
+**Signature:**
+
+```typescript
+function useConstructorPageActions(
+  options: UseConstructorPageActionsOptions
+): UseConstructorPageActionsResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| projectId | `string` | Current project ID |
+| pages | `TourPage[]` | All pages |
+| activePage | `TourPage \| null` | Current page |
+| activePageId | `string` | Current page ID |
+| elements | `CanvasElement[]` | Current elements |
+| backgroundImageUrl | `string` | Background image |
+| backgroundVideoUrl | `string` | Background video |
+| backgroundAudioUrl | `string` | Background audio |
+| onReload | `(preservePageId?) => Promise<void>` | Reload callback |
+| onSetActivePageId | `(id) => void` | Set active page |
+| onSetMenuOpen | `(open) => void` | Set menu open |
+| onError | `(message) => void` | Error callback |
+| onSuccess | `(message) => void` | Success callback |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| isSaving | `boolean` | Save in progress |
+| isSavingToStage | `boolean` | Stage save in progress |
+| isCreatingPage | `boolean` | Page creation in progress |
+| isCreatingTransition | `boolean` | Transition creation in progress |
+| saveConstructor | `() => Promise<void>` | Save current state |
+| saveToStage | `() => Promise<void>` | Save dev → stage |
+| createPage | `() => Promise<void>` | Create new page |
+| createTransition | `(params) => Promise<void>` | Create transition (legacy) |
+
+**Example:**
+
+```typescript
+const {
+  isSaving,
+  saveConstructor,
+  createPage,
+  isCreatingPage,
+} = useConstructorPageActions({
+  projectId,
+  pages,
+  activePage,
+  activePageId,
+  elements,
+  backgroundImageUrl,
+  backgroundVideoUrl,
+  backgroundAudioUrl,
+  onReload: loadData,
+  onSetActivePageId: setActivePageId,
+  onError: setErrorMessage,
+  onSuccess: setSuccessMessage,
+});
+
+// Save changes
+await saveConstructor();
+
+// Create new page
+await createPage();
+```
+
+---
+
+### useTransitionPreview
+
+**Source:** `frontend/src/hooks/useTransitionPreview.ts`
+
+Manages transition video preview state in the constructor. Used to preview forward and reverse transitions before navigation.
+
+**Signature:**
+
+```typescript
+function useTransitionPreview(
+  options: UseTransitionPreviewOptions
+): UseTransitionPreviewResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| isNavigationElementType | `(type) => boolean` | Type checker |
+| onError | `(message) => void` | Error callback |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| preview | `TransitionPreviewState \| null` | Current preview |
+| pendingPageId | `string` | Target page ID |
+| openPreview | `(element, direction) => void` | Open preview |
+| openPreviewWithTarget | `(element, direction, pageId) => void` | Open with target |
+| closePreview | `() => void` | Close preview |
+| isActive | `boolean` | Preview active |
+
+**TransitionPreviewState:**
+
+```typescript
+interface TransitionPreviewState {
+  videoUrl: string;
+  storageKey: string;
+  reverseMode: 'none' | 'reverse' | 'separate';
+  reverseVideoUrl?: string;
+  reverseStorageKey?: string;
+  durationSec?: number;
+  title: string;
+}
+```
+
+**Example:**
+
+```typescript
+const {
+  preview,
+  pendingPageId,
+  openPreviewWithTarget,
+  closePreview,
+  isActive,
+} = useTransitionPreview({
+  isNavigationElementType,
+  onError: setErrorMessage,
+});
+
+// Open preview when clicking element
+const handleClick = () => {
+  openPreviewWithTarget(element, 'forward', targetPage.id);
+};
+
+// Use with useTransitionPlayback
+useTransitionPlayback({
+  transition: preview,
+  onComplete: (targetId) => {
+    switchToPage(targetId);
+    closePreview();
+  },
+});
+```
+
+---
+
+### useCanvasElapsedTime
+
+**Source:** `frontend/src/hooks/useCanvasElapsedTime.ts`
+
+Tracks elapsed time since page load for element visibility timing.
+
+**Signature:**
+
+```typescript
+function useCanvasElapsedTime(
+  options: UseCanvasElapsedTimeOptions
+): UseCanvasElapsedTimeResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| pageId | `string` | Current page ID (resets timer) |
+| enabled | `boolean` | Timer active (default: true) |
+| intervalMs | `number` | Update interval (default: 100ms) |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| elapsedSec | `number` | Elapsed time in seconds |
+| reset | `() => void` | Reset to zero |
+| startedAt | `number` | Start timestamp |
+
+**Example:**
+
+```typescript
+const { elapsedSec } = useCanvasElapsedTime({
+  pageId: activePageId,
+  enabled: !isLoading,
+});
+
+// Check if element should be visible
+const isVisible = elapsedSec >= element.appearDelaySec;
+```
+
+**Helper Function:**
+
+```typescript
+import { isElementVisibleAtTime } from '../hooks/useCanvasElapsedTime';
+
+const visible = isElementVisibleAtTime(
+  elapsedSec,
+  element.appearDelaySec,      // delay before appearing
+  element.appearDurationSec,   // duration visible (null = infinite)
+);
+```
+
+---
+
+### useCanvasElementDrag
+
+**Source:** `frontend/src/hooks/useCanvasElementDrag.ts`
+
+Handles dragging of canvas elements with percentage-based positioning.
+
+**Signature:**
+
+```typescript
+function useCanvasElementDrag(
+  options: UseCanvasElementDragOptions
+): UseCanvasElementDragResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| canvasRef | `RefObject<HTMLElement>` | Canvas container ref |
+| onPositionChange | `(id, x, y) => void` | Position update callback |
+| enabled | `boolean` | Dragging enabled (default: true) |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| onElementDragStart | `(event, id, x, y) => void` | Start drag handler |
+| isDragging | `boolean` | Currently dragging |
+| draggedElementId | `string \| null` | Dragged element ID |
+| cancelDrag | `() => void` | Cancel drag |
+
+**Example:**
+
+```typescript
+const { onElementDragStart, isDragging } = useCanvasElementDrag({
+  canvasRef,
+  onPositionChange: (id, x, y) => {
+    elementsHook.updateElementPosition(id, x, y);
+  },
+  enabled: isEditMode,
+});
+
+return (
+  <button
+    onMouseDown={(e) => onElementDragStart(
+      e, element.id, element.xPercent, element.yPercent
+    )}
+  >
+    {element.label}
+  </button>
+);
+```
+
+---
+
+### useIconPreload
+
+**Source:** `frontend/src/hooks/useIconPreload.ts`
+
+Preloads icon images for smooth rendering without flash.
+
+**Signature:**
+
+```typescript
+function useIconPreload(
+  options: UseIconPreloadOptions
+): UseIconPreloadResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| iconUrls | `string[]` | URLs to preload |
+| enabled | `boolean` | Preloading enabled (default: true) |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| preloadedUrlMap | `Record<string, boolean>` | Preload status map |
+| isPreloaded | `(url) => boolean` | Check if URL preloaded |
+| pendingCount | `number` | Icons being preloaded |
+| allPreloaded | `boolean` | All icons ready |
+
+**Example:**
+
+```typescript
+const iconUrls = elements
+  .filter(el => el.iconUrl)
+  .map(el => resolveAssetPlaybackUrl(el.iconUrl));
+
+const { isPreloaded } = useIconPreload({ iconUrls });
+
+// Only render element if icon is ready
+if (element.iconUrl && !isPreloaded(element.iconUrl)) return null;
+```
+
+**Helper Function:**
+
+```typescript
+import { buildIconPreloadTargets } from '../hooks/useIconPreload';
+
+const targets = buildIconPreloadTargets(elements, {
+  isNavigationElementType,
+  isTooltipElementType,
+  isDescriptionElementType,
+});
+```
+
+---
+
+### useMediaDurationProbe
+
+**Source:** `frontend/src/hooks/useMediaDurationProbe.ts`
+
+Probes media durations with caching and deduplication.
+
+**Signature:**
+
+```typescript
+function useMediaDurationProbe(
+  options: UseMediaDurationProbeOptions
+): UseMediaDurationProbeResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| targets | `DurationProbeTarget[]` | Media sources to probe |
+
+**DurationProbeTarget:**
+
+```typescript
+interface DurationProbeTarget {
+  source: string;
+  mediaType: 'video' | 'audio';
+}
+```
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| durationBySource | `Record<string, number \| null>` | Duration map |
+| getDuration | `(source) => number \| null` | Get duration |
+| getDurationNote | `(source) => string` | Get formatted note |
+| isProbing | `boolean` | Probes in progress |
+
+**Example:**
+
+```typescript
+const { getDurationNote, getDuration } = useMediaDurationProbe({
+  targets: [
+    { source: backgroundVideoUrl, mediaType: 'video' },
+    { source: backgroundAudioUrl, mediaType: 'audio' },
+  ],
+});
+
+return <p>{getDurationNote(backgroundVideoUrl)}</p>; // "1:30" or ""
+```
+
+**Helper Function:**
+
+```typescript
+import { buildDurationProbeTargets } from '../hooks/useMediaDurationProbe';
+
+const targets = buildDurationProbeTargets({
+  backgroundVideoUrl,
+  backgroundAudioUrl,
+  selectedElement,
+  elements,
+  isMediaElementType,
+  isVideoPlayerElementType,
+  isNavigationElementType,
+});
+```
+
+---
+
+## Utility Hooks
+
+### useDevCompilationStatus
+
+**Source:** `frontend/src/hooks/useDevCompilationStatus.ts`
+
+Tracks Next.js compilation status in development mode.
+
+**Signature:**
+
+```typescript
+function useDevCompilationStatus(): CompilationStatus
+```
+
+**Returns:** `'ready' | 'compiling' | 'error' | 'initial'`
+
+**Example:**
+
+```typescript
+const status = useDevCompilationStatus();
+
+return (
+  <div>
+    {status === 'compiling' && <TopLoadingBar />}
+    {status === 'error' && <CompilationErrorBanner />}
+    <MainContent />
+  </div>
+);
+```
+
+**Note:** Returns `'ready'` in production mode.
+
+---
+
+### useOutsideClick
+
+**Source:** `frontend/src/hooks/useOutsideClick.ts`
+
+Detects clicks outside specified elements to clear selection. Useful for closing panels, deselecting elements, etc.
+
+**Signature:**
+
+```typescript
+function useOutsideClick(options: UseOutsideClickOptions): void
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| containerRef | `RefObject<HTMLElement>` | Element whose outside clicks to detect |
+| ignoreRefs | `RefObject<HTMLElement>[]` | Additional refs to ignore |
+| ignoreDataAttribute | `string` | Data attribute to check |
+| selectedValue | `string` | Current selected value |
+| onOutsideClick | `() => void` | Click outside callback |
+| enabled | `boolean` | Hook active (default: true) |
+
+**Example:**
+
+```typescript
+useOutsideClick({
+  containerRef: panelRef,
+  ignoreRefs: [buttonRef],
+  onOutsideClick: () => setSelectedId(''),
+  enabled: !!selectedId,
+});
+```
+
+**With Data Attribute:**
+
+```typescript
+useOutsideClick({
+  containerRef: canvasRef,
+  ignoreDataAttribute: 'data-element-id',
+  selectedValue: selectedElementId,
+  onOutsideClick: () => clearSelection(),
+  enabled: !!selectedElementId,
+});
+
+// In element render
+<button data-element-id={element.id}>...</button>
+```
+
+---
+
+### useDraggable
+
+**Source:** `frontend/src/hooks/useDraggable.ts`
+
+Generic draggable panel management with pointer tracking. Used for draggable controls, menus, and editor panels.
+
+**Signature:**
+
+```typescript
+function useDraggable(options?: UseDraggableOptions): UseDraggableResult
+```
+
+**Parameters:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| initialPosition | `Position` | Starting position |
+| minX | `number` | Minimum x (default: 0) |
+| minY | `number` | Minimum y (default: 0) |
+| maxX | `number` | Maximum x (auto-calculated from window) |
+| maxY | `number` | Maximum y (auto-calculated from window) |
+| elementWidth | `number` | Element width for bounds |
+| elementHeight | `number` | Element height for bounds |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| position | `Position` | Current position {x, y} |
+| setPosition | `(pos) => void` | Set position directly |
+| isDragging | `boolean` | Currently dragging |
+| onDragStart | `(event) => void` | Drag start handler |
+| onDragStartIgnoreButtons | `(event) => void` | Drag start (ignores buttons) |
+
+**Example:**
+
+```typescript
+const { position, onDragStart, isDragging } = useDraggable({
+  initialPosition: { x: 20, y: 20 },
+  elementWidth: 400,
+});
+
+return (
+  <div
+    style={{
+      position: 'fixed',
+      left: position.x,
+      top: position.y,
+    }}
+  >
+    <div
+      className="drag-handle"
+      onMouseDown={onDragStart}
+    >
+      Drag Handle
+    </div>
+    <div>Content</div>
+  </div>
+);
+```
+
+**With Button Ignore:**
+
+```typescript
+// Prevent drag when clicking buttons inside the drag handle
+<div onMouseDown={onDragStartIgnoreButtons}>
+  <span>Title</span>
+  <button>Close</button>  {/* Clicking this won't start drag */}
+</div>
+```
+
+---
+
+## Quick Reference Table
+
+| Hook | Category | Primary Use Case |
+|------|----------|------------------|
+| `useAppDispatch` | Redux | Type-safe dispatch |
+| `useAppSelector` | Redux | Type-safe state selection |
+| `useFormSync` | Data | Sync forms with entities |
+| `useEditPageSync` | Data | Edit page data sync |
+| `useDashboardCounts` | Data | Dashboard entity counts |
+| `useEntityTable` | Data | Complete table management |
+| `useCSVHandling` | Data | CSV import/export |
+| `useFilterItems` | Data | Filter state management |
+| `useElementSettingsForm` | Data | Element settings form state |
+| `useOfflineMode` | Offline | Project offline download |
+| `useStorageQuota` | Offline | Storage monitoring |
+| `usePreloadOrchestrator` | Preload | Asset preload with ready blob URLs |
+| `useNeighborGraph` | Preload | Navigation graph building |
+| `useNetworkAware` | Preload | Network condition monitoring |
+| `usePWAPreload` | Preload | PWA asset caching |
+| `usePreloadProgress` | Preload | Preload job tracking |
+| `useReversePlayback` | Media | Reverse video playback |
+| `useTransitionPlayback` | Media | Transition video management |
+| `useBackgroundTransition` | Media | Background fade transition |
+| `usePageDataLoader` | Media | Project/page data loading |
+| `useElementEffects` | Media | Element interactive effects |
+| `usePageSwitch` | Navigation | Smooth page switching without flash |
+| `usePageNavigation` | Navigation | Page state with history |
+| `useAssetUploader` | Upload | Batch asset uploads |
+| `useConstructorElements` | Constructor | Element CRUD operations |
+| `useConstructorPageActions` | Constructor | Page save/create/publish |
+| `useTransitionPreview` | Constructor | Transition video preview |
+| `useCanvasElapsedTime` | Constructor | Elapsed time tracking |
+| `useCanvasElementDrag` | Constructor | Element drag positioning |
+| `useIconPreload` | Constructor | Icon image preloading |
+| `useMediaDurationProbe` | Constructor | Media duration probing |
+| `useDevCompilationStatus` | Utility | Dev mode compilation |
+| `useOutsideClick` | Utility | Click outside detection |
+| `useDraggable` | Utility | Draggable panel management |
+
+---
+
+## File Structure
+
+```
+frontend/src/
+├── hooks/
+│   ├── index.ts                    # Central exports
+│   │
+│   │ # Data Management
+│   ├── useFormSync.ts
+│   ├── useEditPageSync.ts          # Edit page data sync
+│   ├── useDashboardCounts.ts       # Dashboard entity counts
+│   ├── useEntityTable.ts
+│   ├── useCSVHandling.ts
+│   ├── useFilterItems.ts
+│   │
+│   │ # Offline & Caching
+│   ├── useOfflineMode.ts
+│   ├── useStorageQuota.ts
+│   │
+│   │ # Preloading
+│   ├── usePreloadOrchestrator.ts
+│   ├── useNeighborGraph.ts
+│   ├── useNetworkAware.ts
+│   ├── usePWAPreload.ts
+│   ├── usePreloadProgress.ts
+│   │
+│   │ # Media Playback
+│   ├── useReversePlayback.ts
+│   ├── useTransitionPlayback.ts
+│   ├── useBackgroundTransition.ts  # Background fade transition
+│   ├── usePageDataLoader.ts        # Project/page loading
+│   ├── useElementEffects.ts        # Interactive effects
+│   │
+│   │ # Navigation
+│   ├── usePageSwitch.ts
+│   ├── usePageNavigation.ts
+│   │
+│   │ # Constructor-Specific
+│   ├── useConstructorElements.ts   # Element CRUD
+│   ├── useConstructorPageActions.ts # Page save/create/publish
+│   ├── useTransitionPreview.ts     # Transition video preview
+│   ├── useCanvasElapsedTime.ts     # Elapsed time tracking
+│   ├── useCanvasElementDrag.ts     # Element drag positioning
+│   ├── useIconPreload.ts           # Icon image preloading
+│   ├── useMediaDurationProbe.ts    # Media duration probing
+│   │
+│   │ # Utility
+│   ├── useDevCompilationStatus.ts
+│   ├── useOutsideClick.ts          # Click outside detection
+│   └── useDraggable.ts             # Draggable panel management
+│
+├── stores/
+│   └── hooks.ts  (useAppDispatch, useAppSelector)
+│
+└── components/
+    ├── Assets/
+    │   └── useAssetUploader.ts
+    └── ElementSettings/
+        └── useElementSettingsForm.ts
+```
+
+---
+
+## Related Documentation
+
+| Document | Description |
+|----------|-------------|
+| [runtime-presentation.md](./runtime-presentation.md) | RuntimePresentation component - public tour viewer with transitions and offline support |
+| [constructor-page-editor.md](./constructor-page-editor.md) | Constructor page - visual tour builder with element editing |
+| [assets-preloading.md](../../documentation/assets-preloading.md) | Asset preloading architecture and S3 direct download flow |
+| [page-transitions.md](../../documentation/page-transitions.md) | Video transitions stored on navigation elements |
+| [offline-pwa-mode.md](../../documentation/offline-pwa-mode.md) | PWA offline capabilities and caching |
diff --git a/frontend/docs/interfaces-module.md b/frontend/docs/interfaces-module.md
new file mode 100644
index 0000000..10bd318
--- /dev/null
+++ b/frontend/docs/interfaces-module.md
@@ -0,0 +1,1763 @@
+# Frontend Interfaces Module
+
+## Overview
+
+The Interfaces module provides **TypeScript type definitions** for the entire frontend application. It defines entity types, API contracts, Redux state shapes, form configurations, and domain-specific interfaces for the constructor, runtime, and offline systems.
+
+**Primary Location:** `frontend/src/types/`
+
+**Secondary Locations:**
+- `frontend/src/interfaces/` - Legacy UI types
+- `frontend/src/components/*/types.ts` - Component-specific types
+- `frontend/src/lib/*.ts` - Library types
+
+**Total Files:** ~15 type definition files (~2,680+ LOC)
+
+---
+
+## Architecture
+
+```
+frontend/src/
+├── types/                          # Primary type definitions
+│   ├── index.ts           (14 LOC)    # Central re-exports
+│   ├── entities.ts        (276 LOC)   # Entity interfaces
+│   ├── api.ts             (62 LOC)    # API types
+│   ├── redux.ts           (60 LOC)    # Redux state types
+│   ├── forms.ts           (76 LOC)    # Form configuration
+│   ├── filters.ts         (74 LOC)    # Filter/table config
+│   ├── permissions.ts     (122 LOC)   # Permission enum
+│   ├── offline.ts         (194 LOC)   # PWA/offline types
+│   ├── preload.ts         (57 LOC)    # Preload types
+│   ├── runtime.ts         (80 LOC)    # Runtime types
+│   ├── constructor.ts     (418 LOC)   # Constructor types
+│   └── presentation.ts    (107 LOC)   # Shared presentation
+│
+├── interfaces/                     # Legacy UI types
+│   └── index.ts           (122 LOC)   # Menu, color, user types
+│
+├── components/
+│   ├── Constructor/types.ts    (312 LOC)   # Constructor props
+│   ├── ElementSettings/types.ts (293 LOC)  # Settings props
+│   └── DataGrid/configBuilderFactory.tsx   # Column metadata
+│
+└── lib/
+    ├── elementStyles.ts   (146 LOC)   # CSS style interfaces
+    └── elementEffects.ts  (267 LOC)   # Effect interfaces
+```
+
+---
+
+## Type Categories
+
+### Category Overview
+
+| Category | Location | Purpose |
+|----------|----------|---------|
+| **Entities** | `types/entities.ts` | Database model interfaces |
+| **API** | `types/api.ts` | Request/response types |
+| **Redux** | `types/redux.ts` | Store state shapes |
+| **Forms** | `types/forms.ts` | Form field config |
+| **Filters** | `types/filters.ts` | Table/filter config |
+| **Permissions** | `types/permissions.ts` | RBAC enum |
+| **Offline/PWA** | `types/offline.ts` | Offline storage types |
+| **Preload** | `types/preload.ts` | Asset preloading |
+| **Runtime** | `types/runtime.ts` | Presentation playback |
+| **Constructor** | `types/constructor.ts` | Visual editor types |
+| **Presentation** | `types/presentation.ts` | Shared presentation |
+| **UI/Menu** | `interfaces/index.ts` | Navigation config |
+| **Styles** | `lib/elementStyles.ts` | CSS properties |
+| **Effects** | `lib/elementEffects.ts` | Animation config |
+
+---
+
+## Entity Interfaces (`types/entities.ts`)
+
+### Base Entity
+
+All entities extend the base interface:
+
+```typescript
+export interface BaseEntity {
+  id: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+```
+
+### Core Entities
+
+#### User
+
+```typescript
+export interface User extends BaseEntity {
+  firstName?: string;
+  lastName?: string;
+  phoneNumber?: string;
+  email: string;
+  disabled?: boolean;
+  avatar?: ImageFile[];
+  app_role?: Role | null;
+  custom_permissions?: PermissionEntity[];
+  password?: string;
+}
+```
+
+#### Project
+
+```typescript
+export interface Project extends BaseEntity {
+  name: string;
+  slug?: string;
+  description?: string;
+  logo_url?: string;
+  favicon_url?: string;
+  og_image_url?: string;
+}
+```
+
+#### Asset
+
+```typescript
+export interface Asset extends BaseEntity {
+  project?: Project | string | null;
+  name: string;
+  asset_type: 'image' | 'video' | 'audio' | 'file';
+  type?: 'general' | 'icon' | 'background_image' | 'audio' |
+         'video' | 'transition' | 'logo' | 'favicon' | 'document';
+  cdn_url?: string;
+  storage_key?: string;
+  mime_type?: string;
+  size_mb?: number;
+  width_px?: number;
+  height_px?: number;
+  duration_sec?: number;
+  checksum?: string;
+  is_public?: boolean;
+  is_deleted?: boolean;
+  deleted_at_time?: string | Date;
+}
+```
+
+#### TourPage
+
+```typescript
+export interface TourPage extends BaseEntity {
+  project?: Project | string | null;
+  title?: string;
+  slug?: string;
+  background_asset?: Asset | string | null;
+  audio_asset?: Asset | string | null;
+  is_start_page?: boolean;
+  sort_order?: number;
+}
+```
+
+### Entity Type Map
+
+```typescript
+export type EntityName =
+  | 'users' | 'roles' | 'permissions' | 'projects'
+  | 'project_memberships' | 'assets' | 'asset_variants'
+  | 'tour_pages' | 'project_audio_tracks' | 'publish_events'
+  | 'pwa_caches' | 'presigned_url_requests' | 'access_logs'
+  | 'element_type_defaults';
+
+export interface EntityTypeMap {
+  users: User;
+  roles: Role;
+  projects: Project;
+  assets: Asset;
+  tour_pages: TourPage;
+  // ... all 14 entities mapped
+}
+```
+
+### All Entity Interfaces
+
+| Interface | Fields | Purpose |
+|-----------|--------|---------|
+| `User` | 10 | User accounts |
+| `Role` | 2 | Role definitions |
+| `PermissionEntity` | 1 | Permission records |
+| `Project` | 6 | Tour projects |
+| `Asset` | 14 | Media files |
+| `AssetVariant` | 5 | Image variants |
+| `TourPage` | 7 | Tour pages |
+| `PageElement` | 10 | UI elements |
+| `PageLink` | 4 | Navigation links |
+| `Transition` | 5 | Video transitions |
+| `ProjectAudioTrack` | 14 | Audio tracks |
+| `ProjectMembership` | 8 | Team access |
+| `PublishEvent` | 17 | Publish history |
+| `PwaCache` | 4 | PWA cache records |
+| `PresignedUrlRequest` | 11 | URL requests |
+| `AccessLog` | 9 | Audit logs |
+| `UIElement` | 7 | UI components |
+| `ImageFile` | 5 | Upload metadata |
+
+---
+
+## API Interfaces (`types/api.ts`)
+
+### Response Types
+
+```typescript
+// Paginated list response
+export interface PaginatedResponse<T> {
+  rows: T[];
+  count: number;
+}
+
+// API error structure
+export interface ApiError {
+  message?: string;
+  statusCode?: number;
+  errors?: Record<string, { _errors: string[] }>;
+}
+```
+
+### Request Types
+
+```typescript
+// Fetch parameters
+export interface FetchParams {
+  id?: string;
+  query?: string;
+  limit?: number;
+  page?: number;
+}
+
+// List query parameters
+export interface ListQueryParams {
+  page?: number;
+  limit?: number;
+  sort?: 'asc' | 'desc';
+  field?: string;
+  [filterKey: string]: string | number | boolean | undefined;
+}
+
+// Sort model (DataGrid)
+export interface SortModel {
+  field: string;
+  sort: 'asc' | 'desc';
+}
+```
+
+### Mutation Types
+
+```typescript
+// Create/update payload
+export interface MutationPayload<T> {
+  id?: string;
+  data: Partial<T>;
+}
+
+// Delete by IDs
+export interface DeleteByIdsPayload {
+  ids: string[];
+}
+
+// Autocomplete item
+export interface AutocompleteItem {
+  id: string;
+  label: string;
+}
+
+// CSV upload response
+export interface CsvUploadResponse {
+  imported: number;
+  errors?: string[];
+}
+```
+
+---
+
+## Redux Interfaces (`types/redux.ts`)
+
+### Notification State
+
+```typescript
+export interface NotificationState {
+  showNotification: boolean;
+  textNotification: string;
+  typeNotification: 'warn' | 'error' | 'success' | 'info' | '';
+}
+```
+
+### Entity Slice State
+
+```typescript
+// Generic entity state (used by createEntitySlice)
+export interface EntitySliceState<T> {
+  data: T[];
+  loading: boolean;
+  count: number;
+  refetch: boolean;
+  notify: NotificationState;
+}
+
+// Legacy entity slice state (for backward compatibility during migration)
+export interface LegacyEntitySliceState<T> {
+  [entityName: string]: T[] | boolean | number | NotificationState;
+  loading: boolean;
+  count: number;
+  refetch: boolean;
+  notify: NotificationState;
+}
+
+// Slice factory configuration
+export interface EntitySliceConfig {
+  name: string;
+  endpoint: string;
+  singularName?: string; // For notification messages (e.g., "User" instead of "Users")
+}
+```
+
+### Core Slice States
+
+```typescript
+// Auth state
+export interface AuthState {
+  currentUser: User | null;
+  token: string | null;
+  isFetching: boolean;
+  errorMessage: string | null;
+  loadingMessage: string | null;
+  notify: NotificationState;
+}
+
+// Style state
+export interface StyleState {
+  darkMode: boolean;
+  bgLayoutColor: string;
+  focusRingColor: string;
+  corners: string;
+  cardsColor: string;
+}
+
+// Main app state
+export interface MainState {
+  isAsideMobileExpanded: boolean;
+  isAsideLgActive: boolean;
+}
+```
+
+---
+
+## Form Interfaces (`types/forms.ts`)
+
+### Field Types
+
+```typescript
+export type FormFieldType =
+  | 'text' | 'email' | 'number' | 'password'
+  | 'textarea' | 'richtext'
+  | 'select' | 'multiselect'
+  | 'date' | 'datetime'
+  | 'boolean' | 'switch'
+  | 'image' | 'file' | 'enum';
+```
+
+### Field Configuration
+
+```typescript
+export interface FormFieldConfig {
+  name: string;
+  label: string;
+  type: FormFieldType;
+  required?: boolean;
+  placeholder?: string;
+  itemRef?: string;        // Entity for select options
+  showField?: string;      // Display field from options
+  options?: EnumOption[];  // Enum select options
+  uploadPath?: string;     // File upload path
+  fileSchema?: FileSchema; // File constraints
+  min?: number;
+  max?: number;
+  maxLength?: number;
+  className?: string;
+}
+
+export interface EnumOption {
+  value: string;
+  label: string;
+}
+
+export interface FileSchema {
+  size?: number;      // Max bytes
+  formats?: string[]; // Allowed extensions
+}
+```
+
+### Form Page Configuration
+
+```typescript
+export interface FormPageConfig<TFormData> {
+  entityName: string;
+  entityTitle: string;
+  mode: 'create' | 'edit';
+  permission: string;
+  initialValues: TFormData;
+  fields: FormFieldConfig[];
+  listPath?: string;
+}
+
+export type FormSubmitHandler<T> = (values: T) => Promise<void>;
+export type FormValues = Record<string, unknown>;
+```
+
+---
+
+## Filter Interfaces (`types/filters.ts`)
+
+### Filter Configuration
+
+```typescript
+export type FilterType = 'text' | 'enum' | 'date' | 'number' | 'boolean';
+
+export interface Filter {
+  label: string;
+  title: string;       // Field name
+  type?: FilterType;
+  options?: string[];  // For enum filters
+  number?: boolean;
+  date?: boolean;
+}
+
+export interface FilterItem {
+  id: string;
+  fields: FilterFields;
+}
+
+export interface FilterFields {
+  selectedField: string;
+  filterValue: string;
+  filterValueFrom: string;
+  filterValueTo: string;
+}
+
+// Filter request format for API
+export type FilterRequest = Record<string, string | string[]>;
+```
+
+### Table Configuration
+
+```typescript
+export interface TableColumnConfig {
+  field: string;
+  headerName: string;
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  flex?: number;
+  editable?: boolean;
+  sortable?: boolean;
+  filterable?: boolean;
+  type?: 'string' | 'number' | 'date' | 'dateTime' | 'boolean' | 'singleSelect';
+  valueOptions?: string[];
+  renderType?: 'link' | 'boolean' | 'date' | 'datetime' | 'image' | 'actions' | 'relation';
+  relationField?: string;
+}
+
+export interface TableConfig {
+  entityName: string;
+  columns: TableColumnConfig[];
+  filters: Filter[];
+  defaultSort?: { field: string; sort: 'asc' | 'desc' };
+  perPage?: number;
+}
+```
+
+---
+
+## Permission Types (`types/permissions.ts`)
+
+### Permission Enum
+
+```typescript
+export enum Permission {
+  // User permissions
+  READ_USERS = 'READ_USERS',
+  CREATE_USERS = 'CREATE_USERS',
+  UPDATE_USERS = 'UPDATE_USERS',
+  DELETE_USERS = 'DELETE_USERS',
+
+  // Project permissions
+  READ_PROJECTS = 'READ_PROJECTS',
+  CREATE_PROJECTS = 'CREATE_PROJECTS',
+  UPDATE_PROJECTS = 'UPDATE_PROJECTS',
+  DELETE_PROJECTS = 'DELETE_PROJECTS',
+
+  // Asset permissions
+  READ_ASSETS = 'READ_ASSETS',
+  CREATE_ASSETS = 'CREATE_ASSETS',
+  UPDATE_ASSETS = 'UPDATE_ASSETS',
+  DELETE_ASSETS = 'DELETE_ASSETS',
+
+  // ... 15 more entity permission groups
+}
+```
+
+### Permission Helpers
+
+```typescript
+export type PermissionString = `${Permission}` | string;
+
+// Get CRUD permissions for any entity
+export const getEntityPermissions = (entityName: string) => {
+  const uppercased = entityName.toUpperCase();
+  return {
+    read: `READ_${uppercased}` as PermissionString,
+    create: `CREATE_${uppercased}` as PermissionString,
+    update: `UPDATE_${uppercased}` as PermissionString,
+    delete: `DELETE_${uppercased}` as PermissionString,
+  };
+};
+```
+
+### Permission Categories
+
+| Entity | Permissions |
+|--------|-------------|
+| Users | READ, CREATE, UPDATE, DELETE |
+| Roles | READ, CREATE, UPDATE, DELETE |
+| Permissions | READ, CREATE, UPDATE, DELETE |
+| Projects | READ, CREATE, UPDATE, DELETE |
+| Project Memberships | READ, CREATE, UPDATE, DELETE |
+| Assets | READ, CREATE, UPDATE, DELETE |
+| Asset Variants | READ, CREATE, UPDATE, DELETE |
+| Tour Pages | READ, CREATE, UPDATE, DELETE |
+| Page Elements | READ, CREATE, UPDATE, DELETE |
+| Page Links | READ, CREATE, UPDATE, DELETE |
+| Transitions | READ, CREATE, UPDATE, DELETE |
+| Project Audio Tracks | READ, CREATE, UPDATE, DELETE |
+| Publish Events | READ, CREATE, UPDATE, DELETE |
+| PWA Caches | READ, CREATE, UPDATE, DELETE |
+| Presigned URL Requests | READ, CREATE, UPDATE, DELETE |
+| Access Logs | READ, CREATE, UPDATE, DELETE |
+| UI Elements | READ, CREATE, UPDATE, DELETE |
+
+**Total: 68 permissions (17 entities × 4 CRUD operations)**
+
+---
+
+## Offline/PWA Interfaces (`types/offline.ts`)
+
+### Asset Types
+
+```typescript
+export type AssetVariantType =
+  | 'thumbnail' | 'preview' | 'webp'
+  | 'mp4_low' | 'mp4_high' | 'original';
+
+export type AssetType = 'image' | 'video' | 'audio' | 'transition' | 'other';
+
+export type PreloadJobStatus =
+  | 'queued' | 'downloading' | 'completed' | 'error' | 'paused';
+```
+
+### Preload Job
+
+```typescript
+export interface PreloadJob {
+  id: string;
+  assetId: string;
+  url: string;
+  filename: string;
+  progress: number;
+  status: PreloadJobStatus;
+  bytesLoaded: number;
+  totalBytes: number;
+  pageId?: string;
+  variantType?: AssetVariantType;
+  assetType?: AssetType;
+  error?: string;
+  addedAt: number;
+  startedAt?: number;
+  completedAt?: number;
+}
+```
+
+### Offline Project
+
+```typescript
+export type ProjectOfflineStatus =
+  | 'not_downloaded' | 'downloading' | 'downloaded' | 'outdated' | 'error';
+
+export interface OfflineProject {
+  id: string;
+  slug: string;
+  name: string;
+  status: ProjectOfflineStatus;
+  totalAssets: number;
+  downloadedAssets: number;
+  totalSizeBytes: number;
+  downloadedSizeBytes: number;
+  lastSyncedAt?: number;
+  version?: string;
+}
+```
+
+### Storage Types
+
+```typescript
+export interface OfflineAsset {
+  id: string;
+  projectId: string;
+  url: string;
+  filename: string;
+  variantType: AssetVariantType;
+  assetType: AssetType;
+  mimeType: string;
+  sizeBytes: number;
+  blob: Blob;
+  downloadedAt: number;
+}
+
+export interface DownloadQueueItem {
+  id: string;
+  projectId: string;
+  assetId: string;
+  url: string;
+  filename: string;
+  status: PreloadJobStatus;
+  priority: number;
+  retryCount: number;
+  bytesLoaded: number;
+  totalBytes: number;
+  addedAt: number;
+  lastAttemptAt?: number;
+  error?: string;
+}
+```
+
+### Network/Storage Info
+
+```typescript
+export interface NetworkInfo {
+  isOnline: boolean;
+  effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
+  downlink?: number;  // Mbps
+  rtt?: number;       // ms
+  saveData?: boolean;
+}
+
+export interface StorageQuotaInfo {
+  usage: number;
+  quota: number;
+  percentUsed: number;
+  available: number;
+  canStore: (bytes: number) => boolean;
+}
+```
+
+### Manifest Types
+
+```typescript
+export interface OfflineManifest {
+  version: string;
+  projectId: string;
+  projectSlug: string;
+  assets: ManifestAsset[];
+  totalSizeBytes: number;
+  generatedAt: number;
+}
+
+export interface ManifestAsset {
+  id: string;
+  url: string;
+  filename: string;
+  variantType: AssetVariantType;
+  assetType: AssetType;
+  mimeType: string;
+  sizeBytes: number;
+  pageIds: string[];
+}
+```
+
+### Preload State Types
+
+```typescript
+// Preload orchestrator state
+export interface PreloadState {
+  isActive: boolean;
+  currentPageId: string | null;
+  queuedAssets: string[];
+  loadingAssets: string[];
+  completedAssets: string[];
+  failedAssets: string[];
+  totalProgress: number;
+}
+
+// Neighbor graph for preloading
+export interface NeighborGraph {
+  // Map from pageId to array of connected pageIds with distance
+  connections: Map<string, Array<{ pageId: string; distance: number }>>;
+  // Get neighbors within a certain depth
+  getNeighbors: (pageId: string, maxDepth: number) => string[];
+  // Get all assets for a set of pages
+  getAssetsForPages: (pageIds: string[]) => string[];
+}
+```
+
+### Event Types
+
+```typescript
+export interface PreloadStartEvent {
+  jobId: string;
+  assetId: string;
+  url: string;
+}
+
+export interface PreloadProgressEvent {
+  jobId: string;
+  progress: number;
+  bytesLoaded: number;
+  totalBytes: number;
+}
+
+export interface PreloadCompleteEvent {
+  jobId: string;
+  assetId: string;
+}
+
+export interface PreloadErrorEvent {
+  jobId: string;
+  assetId: string;
+  error: string;
+}
+
+export interface ProjectDownloadProgressEvent {
+  projectId: string;
+  progress: number;
+  downloadedAssets: number;
+  totalAssets: number;
+  downloadedBytes: number;
+  totalBytes: number;
+}
+
+export interface ProjectDownloadCompleteEvent {
+  projectId: string;
+}
+```
+
+---
+
+## Preload Interfaces (`types/preload.ts`)
+
+### Page Types
+
+```typescript
+export interface PreloadPage {
+  id: string;
+  background_image_url?: string;
+  background_video_url?: string;
+  background_audio_url?: string;
+}
+
+export interface PreloadPageLink {
+  id: string;
+  from_pageId?: string;
+  to_pageId?: string;
+  is_active?: boolean;
+  transition?: {
+    id: string;
+    video_url?: string;
+  };
+}
+
+export interface PreloadElement {
+  id: string;
+  pageId?: string;
+  element_type?: string;
+  content_json?: string;
+}
+```
+
+### Asset Info
+
+```typescript
+export interface PreloadAssetInfo {
+  url: string;
+  pageId: string;
+  assetType: 'image' | 'video' | 'audio' | 'transition' | 'other';
+  priority: number;
+}
+
+export interface PreloadNeighborInfo {
+  pageId: string;
+  distance: number;
+}
+```
+
+---
+
+## Runtime Interfaces (`types/runtime.ts`)
+
+### Runtime Types
+
+```typescript
+export interface RuntimeProject {
+  id: string;
+  name?: string;
+  slug?: string;
+  description?: string;
+}
+
+export interface RuntimePage extends PreloadPage {
+  slug?: string;
+  name?: string;
+  sort_order?: number;
+  ui_schema_json?: string;
+  environment?: 'dev' | 'stage' | 'production';
+}
+
+export interface RuntimePageLink extends PreloadPageLink {
+  transitionId?: string;
+  direction?: string;
+  external_url?: string;
+  trigger_selector?: string;
+}
+
+export interface RuntimeElement extends PreloadElement {
+  name?: string;
+  sort_order?: number;
+  is_visible?: boolean;
+  x_percent?: number;
+  y_percent?: number;
+  width_percent?: number;
+  height_percent?: number;
+  rotation_deg?: number;
+  style_json?: string;
+}
+
+export interface RuntimeTransition {
+  id: string;
+  name?: string;
+  slug?: string;
+  video_url?: string;
+  duration_sec?: number;
+  supports_reverse?: boolean;
+}
+```
+
+### Transition State
+
+```typescript
+export interface TransitionOverlayState {
+  targetPageId: string;
+  transitionName: string;
+  videoUrl: string;
+  isReverse: boolean;
+  durationSec?: number;
+}
+```
+
+---
+
+## Constructor Interfaces (`types/constructor.ts`)
+
+### Element Types
+
+```typescript
+export type CanvasElementType =
+  | 'navigation_next'  // Forward navigation
+  | 'navigation_prev'  // Back navigation
+  | 'spot'             // Hotspot
+  | 'description'      // Text block
+  | 'tooltip'          // Hover tooltip
+  | 'gallery'          // Image gallery
+  | 'carousel'         // Image carousel
+  | 'logo'             // Logo element
+  | 'video_player'     // Video player
+  | 'audio_player'     // Audio player
+  | 'popup';           // Popup/modal
+
+export type NavigationButtonKind = 'forward' | 'back';
+```
+
+### Canvas Element
+
+```typescript
+export interface BaseCanvasElement
+  extends ElementStyleProperties,
+    ElementEffectProperties {
+  id: string;
+  type: CanvasElementType | string;
+  label?: string;
+  xPercent?: number;
+  yPercent?: number;
+  iconUrl?: string;
+  appearDelaySec?: number;
+  appearDurationSec?: number | null;
+}
+
+export interface CanvasElement extends BaseCanvasElement {
+  type: CanvasElementType;
+  label: string;
+  xPercent: number;
+  yPercent: number;
+
+  // Media
+  mediaUrl?: string;
+  mediaAutoplay?: boolean;
+  mediaLoop?: boolean;
+  mediaMuted?: boolean;
+  backgroundImageUrl?: string;
+  videoUrl?: string;
+  audioUrl?: string;
+
+  // Gallery
+  galleryCards?: GalleryCard[];
+  galleryHeaderImageUrl?: string;
+  galleryTitle?: string;
+  galleryInfoSpans?: GalleryInfoSpan[];
+  galleryColumns?: number;
+  galleryTitleFontFamily?: string;
+  galleryCardFontFamily?: string;
+
+  // Carousel
+  carouselSlides?: CarouselSlide[];
+  carouselCaptionFontFamily?: string;
+  carouselPrevIconUrl?: string;
+  carouselNextIconUrl?: string;
+
+  // Tooltip
+  tooltipTitle?: string;
+  tooltipText?: string;
+  tooltipTitleFontFamily?: string;
+  tooltipTextFontFamily?: string;
+
+  // Description
+  descriptionTitle?: string;
+  descriptionText?: string;
+  descriptionTitleFontSize?: string;
+  descriptionTextFontSize?: string;
+  descriptionTitleFontFamily?: string;
+  descriptionTextFontFamily?: string;
+  descriptionTitleColor?: string;
+  descriptionTextColor?: string;
+  descriptionBackgroundColor?: string;
+
+  // Navigation
+  navLabel?: string;
+  navType?: NavigationButtonKind;
+  navDisabled?: boolean;
+  /** @deprecated Use targetPageSlug instead */
+  targetPageId?: string;
+  targetPageSlug?: string;
+  transitionVideoUrl?: string;
+  transitionReverseMode?: 'auto_reverse' | 'separate_video';
+  reverseVideoUrl?: string;
+  transitionDurationSec?: number;
+
+  // Gallery Carousel Settings
+  galleryCarouselPrevIconUrl?: string;
+  galleryCarouselNextIconUrl?: string;
+  galleryCarouselBackIconUrl?: string;
+  galleryCarouselBackLabel?: string;
+  galleryCarouselPrevX?: number;
+  galleryCarouselPrevY?: number;
+  galleryCarouselNextX?: number;
+  galleryCarouselNextY?: number;
+  galleryCarouselBackX?: number;
+  galleryCarouselBackY?: number;
+  galleryCarouselPrevWidth?: string;
+  galleryCarouselPrevHeight?: string;
+  galleryCarouselNextWidth?: string;
+  galleryCarouselNextHeight?: string;
+  galleryCarouselBackWidth?: string;
+  galleryCarouselBackHeight?: string;
+}
+```
+
+### Collection Items
+
+```typescript
+export interface GalleryCard {
+  id: string;
+  imageUrl: string;
+  title: string;
+  description: string;
+}
+
+export interface GalleryInfoSpan {
+  id: string;
+  text: string;
+}
+
+export interface CarouselSlide {
+  id: string;
+  imageUrl: string;
+  caption: string;
+}
+```
+
+### Constructor Schema
+
+```typescript
+export interface ConstructorSchema {
+  elements?: CanvasElement[];
+}
+```
+
+### Asset Types
+
+```typescript
+export interface ConstructorAsset {
+  id: string;
+  name?: string;
+  asset_type?: 'image' | 'video' | 'audio' | 'file';
+  type?: 'icon' | 'background_image' | 'audio' | 'video' |
+         'transition' | 'logo' | 'favicon' | 'document' | 'general';
+  cdn_url?: string | null;
+  storage_key?: string | null;
+}
+
+export interface AssetOption {
+  value: string;
+  label: string;
+}
+```
+
+### Element Defaults
+
+```typescript
+export interface UiElementDefault {
+  id: string;
+  element_type?: string;
+  is_active?: boolean;
+  default_settings_json?: string | Record<string, unknown>;
+}
+
+export interface NormalizedElementDefault {
+  id: string;
+  element_type: string;
+  name?: string;
+  sort_order?: number;
+  settings: Partial<CanvasElement>;
+}
+```
+
+### Editor Props Interfaces
+
+```typescript
+export interface EditorLayoutProps {
+  elementEditorRef: React.RefObject<HTMLDivElement | null>;
+  position: { x: number; y: number };
+  isCollapsed: boolean;
+  onToggleCollapse: () => void;
+  onDragStart: (event: React.MouseEvent) => void;
+}
+
+export interface EditorStateProps {
+  title: string;
+  activeTab: 'general' | 'css' | 'effects';
+  onTabChange: (tab: 'general' | 'css' | 'effects') => void;
+}
+
+export interface EditorElementProps {
+  selectedElement: CanvasElement | null;
+  selectedMenuItem: 'none' | 'background_image' | 'background_video' |
+                    'background_audio' | 'create_transition';
+  onRemoveElement: () => void;
+  onUpdateElement: (patch: Partial<CanvasElement>) => void;
+}
+
+export interface EditorBackgroundProps {
+  backgroundImageUrl: string;
+  backgroundVideoUrl: string;
+  backgroundAudioUrl: string;
+  onBackgroundImageChange: (value: string) => void;
+  onBackgroundVideoChange: (value: string) => void;
+  onBackgroundAudioChange: (value: string) => void;
+}
+
+export interface EditorTransitionProps {
+  newTransitionName: string;
+  newTransitionVideoUrl: string;
+  newTransitionSupportsReverse: boolean;
+  isCreatingTransition: boolean;
+  onNewTransitionNameChange: (value: string) => void;
+  onNewTransitionVideoUrlChange: (value: string) => void;
+  onNewTransitionSupportsReverseChange: (value: boolean) => void;
+  onCreateTransition: () => void;
+}
+
+export interface EditorDurationNotesProps {
+  backgroundVideoDurationNote: string;
+  backgroundAudioDurationNote: string;
+  newTransitionDurationNote: string;
+  selectedMediaDurationNote: string;
+  selectedTransitionDurationNote: string;
+}
+
+export interface EditorAssetOptionsProps {
+  backgroundImageAssetOptions: AssetOption[];
+  videoAssetOptions: AssetOption[];
+  audioAssetOptions: AssetOption[];
+  transitionVideoAssetOptions: AssetOption[];
+  iconAssetOptions: AssetOption[];
+  imageAssetOptions: AssetOption[];
+}
+
+export interface EditorNavigationProps {
+  allowedNavigationTypes: Array<'navigation_next' | 'navigation_prev'>;
+  pages: Array<{
+    id: string;
+    name?: string;
+    slug?: string;
+    sort_order?: number;
+  }>;
+  activePageId: string;
+  onPreviewTransition: (direction: 'forward' | 'back') => void;
+  normalizeNavigationType: (
+    element: CanvasElement,
+    nextType: 'navigation_next' | 'navigation_prev',
+  ) => CanvasElement;
+}
+
+export interface EditorCollectionOpsProps {
+  galleryCards: {
+    add: () => void;
+    update: (cardId: string, patch: Partial<GalleryCard>) => void;
+    remove: (cardId: string) => void;
+  };
+  galleryInfoSpans: {
+    add: () => void;
+    update: (spanId: string, text: string) => void;
+    remove: (spanId: string) => void;
+  };
+  carouselSlides: {
+    add: () => void;
+    update: (slideId: string, patch: Partial<CarouselSlide>) => void;
+    remove: (slideId: string) => void;
+  };
+}
+
+export interface EditorMediaUtilsProps {
+  getDuration: (url: string) => number | undefined;
+}
+```
+
+---
+
+## Presentation Interfaces (`types/presentation.ts`)
+
+### State Types
+
+```typescript
+export interface TransitionPreviewState {
+  targetPageId: string;
+  videoUrl: string;
+  storageKey: string;
+  isReverse: boolean;
+}
+
+export interface BackgroundState {
+  imageUrl: string;
+  videoUrl: string;
+  audioUrl: string;
+}
+
+export interface NavigationTarget {
+  page: RuntimePage;
+  pageId: string;
+  transitionVideoUrl?: string;
+  isBack: boolean;
+}
+```
+
+### API Configuration
+
+```typescript
+export interface RuntimeApiConfig {
+  headers: {
+    'X-Runtime-Project-Slug'?: string;
+    'X-Runtime-Environment'?: string;
+  };
+}
+
+export interface PageDataLoaderResult {
+  project: RuntimeProject | null;
+  pages: RuntimePage[];
+  isLoading: boolean;
+  error: string;
+  reload: (preservePageId?: string) => Promise<void>;
+}
+
+// Runtime project (duplicate in presentation.ts)
+export interface RuntimeProject {
+  id: string;
+  name?: string;
+  slug?: string;
+  description?: string;
+}
+```
+
+### Navigation Types
+
+```typescript
+export interface NavigableElement {
+  id: string;
+  type: string;
+  targetPageSlug?: string;
+  targetPageId?: string;
+  transitionVideoUrl?: string;
+  navType?: 'forward' | 'back';
+  navDisabled?: boolean;
+}
+```
+
+### Transition Types
+
+```typescript
+export type TransitionPhase =
+  | 'idle'
+  | 'preparing'
+  | 'playing'
+  | 'reversing'
+  | 'completed';
+
+export interface BackgroundTransitionOptions {
+  pendingTransitionComplete: boolean;
+  isBackgroundReady: boolean;
+  transitionVideoRef: React.RefObject<HTMLVideoElement | null>;
+  pageSwitch: {
+    clearPreviousBackground: () => void;
+    isSwitching: boolean;
+    isNewBgReady: boolean;
+    previousBgImageUrl: string;
+  };
+  onCleanup: () => void;
+}
+```
+
+---
+
+## UI/Menu Interfaces (`interfaces/index.ts`)
+
+### Menu Types
+
+```typescript
+export type MenuAsideItem = {
+  label: string;
+  icon?: string;
+  href?: string;
+  target?: string;
+  color?: ColorButtonKey;
+  isLogout?: boolean;
+  withDevider?: boolean;
+  menu?: MenuAsideItem[];
+  permissions?: string | string[];
+};
+
+export type MenuNavBarItem = {
+  label?: string;
+  icon?: string;
+  href?: string;
+  target?: string;
+  isDivider?: boolean;
+  isLogout?: boolean;
+  isDesktopNoLabel?: boolean;
+  isToggleLightDark?: boolean;
+  isCurrentUser?: boolean;
+  menu?: MenuNavBarItem[];
+};
+```
+
+### Color Types
+
+```typescript
+export type ColorKey =
+  | 'white' | 'light' | 'contrast'
+  | 'success' | 'danger' | 'warning' | 'info';
+
+export type ColorButtonKey =
+  | 'white' | 'whiteDark' | 'lightDark' | 'contrast'
+  | 'success' | 'danger' | 'warning' | 'info' | 'void';
+
+export type BgKey = 'purplePink' | 'pinkRed' | 'violet';
+
+export type StyleKey = 'white' | 'basic';
+```
+
+---
+
+## Style Interfaces (`lib/elementStyles.ts`)
+
+### CSS Style Properties
+
+```typescript
+export interface ElementStyleProperties {
+  width?: string;
+  height?: string;
+  minWidth?: string;
+  maxWidth?: string;
+  minHeight?: string;
+  maxHeight?: string;
+  margin?: string;
+  padding?: string;
+  gap?: string;
+  fontSize?: string;
+  lineHeight?: string;
+  fontWeight?: string;
+  border?: string;
+  borderRadius?: string;
+  opacity?: string;
+  boxShadow?: string;
+  display?: string;
+  position?: string;
+  justifyContent?: string;
+  alignItems?: string;
+  textAlign?: string;
+  zIndex?: string;
+  backgroundColor?: string;
+  color?: string;
+  fontFamily?: string;
+}
+
+export const ELEMENT_STYLE_PROPS = [
+  'width', 'height', 'minWidth', 'maxWidth', 'minHeight', 'maxHeight',
+  'margin', 'padding', 'gap', 'fontSize', 'lineHeight', 'fontWeight',
+  'border', 'borderRadius', 'boxShadow', 'display', 'position',
+  'justifyContent', 'alignItems', 'textAlign', 'zIndex',
+  'backgroundColor', 'color', 'fontFamily',
+] as const;
+```
+
+---
+
+## Effect Interfaces (`lib/elementEffects.ts`)
+
+### Animation Types
+
+```typescript
+export type AppearAnimationType =
+  | '' | 'fade' | 'slide-up' | 'slide-down'
+  | 'slide-left' | 'slide-right' | 'scale';
+```
+
+### Effect Properties
+
+```typescript
+export interface ElementEffectProperties {
+  // Appear animation
+  appearAnimation?: AppearAnimationType;
+  appearAnimationDuration?: string;
+  appearAnimationEasing?: string;
+
+  // Hover effects
+  hoverScale?: string;
+  hoverOpacity?: string;
+  hoverBackgroundColor?: string;
+  hoverColor?: string;
+  hoverBoxShadow?: string;
+  hoverTransitionDuration?: string;
+
+  // Focus effects
+  focusScale?: string;
+  focusOpacity?: string;
+  focusOutline?: string;
+  focusBoxShadow?: string;
+
+  // Active/press effects
+  activeScale?: string;
+  activeOpacity?: string;
+  activeBackgroundColor?: string;
+}
+
+export const EFFECT_PROPS = [
+  'appearAnimation', 'appearAnimationDuration', 'appearAnimationEasing',
+  'hoverScale', 'hoverOpacity', 'hoverBackgroundColor', 'hoverColor',
+  'hoverBoxShadow', 'hoverTransitionDuration',
+  'focusScale', 'focusOpacity', 'focusOutline', 'focusBoxShadow',
+  'activeScale', 'activeOpacity', 'activeBackgroundColor',
+] as const;
+```
+
+---
+
+## Component Types
+
+### Constructor Component Types (`components/Constructor/types.ts`)
+
+```typescript
+export type ConstructorInteractionMode = 'edit' | 'interact';
+
+export type EditorMenuItem =
+  | 'none' | 'background_image' | 'background_video'
+  | 'background_audio' | 'create_transition';
+
+export type ElementEditorTab = 'general' | 'css' | 'effects';
+
+export interface Position {
+  x: number;
+  y: number;
+}
+
+export interface CanvasElementProps {
+  element: CanvasElement;
+  isSelected: boolean;
+  isEditMode: boolean;
+  isDisabled?: boolean;
+  canvasElapsedSec: number;
+  preloadedIconUrl: boolean;
+  onClick: (element: CanvasElement) => void;
+  onMouseDown?: (event: React.MouseEvent, elementId: string) => void;
+}
+
+export interface ConstructorCanvasProps {
+  canvasRef: React.RefObject<HTMLDivElement>;
+  elements: CanvasElement[];
+  selectedElementId: string;
+  isEditMode: boolean;
+  isLoading: boolean;
+  canvasElapsedSec: number;
+  preloadedIconUrlMap: Record<string, boolean>;
+  background: CanvasBackgroundProps;
+  transitionPreview: boolean;
+  isReverseBuffering: boolean;
+  onElementClick: (element: CanvasElement) => void;
+  onElementMouseDown: (event: React.MouseEvent, elementId: string) => void;
+  onCreatePage: () => void;
+  isCreatingPage: boolean;
+}
+```
+
+### Element Settings Types (`components/ElementSettings/types.ts`)
+
+```typescript
+export type ElementSettingsContext =
+  | 'global'       // element-type-defaults page
+  | 'project'      // project-element-defaults page
+  | 'constructor'; // constructor page
+
+export interface StyleSettingsSectionProps {
+  values: ElementStyleProperties;
+  onChange: (prop: keyof ElementStyleProperties, value: string) => void;
+}
+
+export interface NavigationSettingsSectionProps {
+  iconUrl: string;
+  navLabel: string;
+  navType: 'forward' | 'back';
+  navDisabled: boolean;
+  targetPageId: string;
+  targetPageSlug: string;
+  transitionVideoUrl: string;
+  transitionReverseMode: 'auto_reverse' | 'separate_video';
+  reverseVideoUrl: string;
+  onChange: (field: string, value: string | boolean) => void;
+  context: ElementSettingsContext;
+  iconAssetOptions?: AssetOption[];
+  transitionVideoAssetOptions?: AssetOption[];
+  pageOptions?: { value: string; label: string }[];
+}
+```
+
+### DataGrid Column Types (`components/DataGrid/configBuilderFactory.tsx`)
+
+```typescript
+export interface ColumnMetadata {
+  field: string;
+  headerName: string;
+  type?: 'text' | 'boolean' | 'date' | 'datetime' | 'number' |
+         'relation' | 'relationMany' | 'singleSelectRelation' |
+         'image' | 'actions';
+  editable?: boolean;
+  sortable?: boolean;
+  width?: number;
+  flex?: number;
+  minWidth?: number;
+  entityRef?: string;
+  displayField?: string;
+  renderCell?: (params: GridRenderCellParams) => React.ReactElement;
+  valueFormatter?: (value: unknown) => string;
+}
+
+export interface ColumnBuilderConfig {
+  entityName: string;
+  entityPath?: string;
+  columns: ColumnMetadata[];
+  updatePermission?: string;
+}
+```
+
+---
+
+## Hook Interfaces
+
+### usePageSwitch
+
+```typescript
+export interface SwitchablePage {
+  id: string;
+  background_image_url?: string;
+  background_video_url?: string;
+  background_audio_url?: string;
+}
+
+export interface PreloadCacheProvider {
+  getReadyBlobUrl?: (url: string) => string | null;
+  getCachedBlobUrl?: (url: string) => Promise<string | null>;
+  preloadedUrls?: Set<string>;
+}
+
+export interface UsePageSwitchOptions {
+  preloadCache?: PreloadCacheProvider;
+}
+
+export interface UsePageSwitchResult {
+  currentBgImageUrl: string;
+  currentBgVideoUrl: string;
+  currentBgAudioUrl: string;
+  previousBgImageUrl: string;
+  isSwitching: boolean;
+  isNewBgReady: boolean;
+  // ... additional methods
+}
+```
+
+### useTransitionPlayback
+
+```typescript
+export type ReverseMode = 'none' | 'reverse' | 'separate';
+
+export interface TransitionConfig {
+  videoUrl: string;
+  storageKey?: string;
+  reverseMode: ReverseMode;
+  reverseVideoUrl?: string;
+  durationSec?: number;
+  targetPageId?: string;
+  displayName?: string;
+}
+
+export interface UseTransitionPlaybackOptions {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  transition: TransitionConfig | null;
+  onComplete: (targetPageId?: string) => void;
+  onError?: (reason: string) => void;
+  timeouts?: { ... };
+  features?: { ... };
+  preload?: { ... };
+}
+
+export type PlaybackPhase =
+  | 'idle' | 'preparing' | 'playing'
+  | 'reversing' | 'finishing' | 'completed';
+
+export interface UseTransitionPlaybackResult {
+  phase: PlaybackPhase;
+  isBuffering: boolean;
+  isReversing: boolean;
+  cancel: () => void;
+  forceComplete: () => void;
+}
+```
+
+---
+
+## Type Utilities
+
+### Type Guards
+
+```typescript
+// Canvas element type guard
+export function isCanvasElementType(value: string): value is CanvasElementType {
+  return CANVAS_ELEMENT_TYPES.includes(value as CanvasElementType);
+}
+```
+
+### Normalization Functions
+
+```typescript
+// Normalize element default from API
+export function normalizeElementDefault(
+  row: Record<string, unknown>,
+): NormalizedElementDefault | null;
+
+// Build defaults map
+export function buildElementDefaultsMap(
+  defaults: NormalizedElementDefault[],
+): Partial<Record<CanvasElementType, Partial<CanvasElement>>>;
+```
+
+### Value Helpers (ElementSettings)
+
+```typescript
+export const clampPercent = (value: string): number;
+export const parseNullableNumber = (value: string): number | null;
+export const extractNumericValue = (value: unknown): string;
+export const normalizeNumberString = (value: string): string;
+export const toOptionalTrimmed = (value: string): string | undefined;
+export const toUnitValue = (value: string, unit: 'vw' | 'vh' | 'px'): string | undefined;
+```
+
+---
+
+## Import Patterns
+
+### Central Index Exports
+
+The central `types/index.ts` re-exports all core type modules:
+
+```typescript
+export * from './entities';
+export * from './api';
+export * from './redux';
+export * from './forms';
+export * from './filters';
+export * from './permissions';
+export * from './offline';
+export * from './preload';
+export * from './runtime';
+export * from './constructor';
+// Note: presentation.ts is NOT exported from index
+```
+
+### Central Import
+
+```typescript
+// Import all types from central index
+import {
+  User,
+  Project,
+  Asset,
+  PaginatedResponse,
+  Permission,
+  PreloadJob,
+  CanvasElement,
+} from '@/types';
+```
+
+### Domain-Specific Import
+
+```typescript
+// Import from specific modules
+import { CanvasElement, CanvasElementType } from '@/types/constructor';
+import { PreloadJob, OfflineProject } from '@/types/offline';
+import { RuntimePage, RuntimeTransition } from '@/types/runtime';
+```
+
+### Component Types Import
+
+```typescript
+// Import component-specific types
+import type {
+  ConstructorCanvasProps,
+  ElementEditorPanelProps,
+} from '@/components/Constructor/types';
+```
+
+---
+
+## File Inventory
+
+| File | LOC | Interfaces | Types | Enums |
+|------|-----|------------|-------|-------|
+| `types/entities.ts` | 276 | 18 | 2 | 0 |
+| `types/api.ts` | 62 | 9 | 0 | 0 |
+| `types/redux.ts` | 60 | 7 | 0 | 0 |
+| `types/forms.ts` | 76 | 5 | 2 | 0 |
+| `types/filters.ts` | 74 | 6 | 2 | 0 |
+| `types/permissions.ts` | 122 | 0 | 1 | 1 |
+| `types/offline.ts` | 194 | 16 | 3 | 0 |
+| `types/preload.ts` | 57 | 5 | 0 | 0 |
+| `types/runtime.ts` | 80 | 7 | 0 | 0 |
+| `types/constructor.ts` | 418 | 25 | 2 | 0 |
+| `types/presentation.ts` | 107 | 9 | 1 | 0 |
+| `types/index.ts` | 14 | 0 | 0 | 0 |
+| `interfaces/index.ts` | 122 | 4 | 10 | 0 |
+| `components/Constructor/types.ts` | 312 | 20 | 3 | 0 |
+| `components/ElementSettings/types.ts` | 293 | 12 | 1 | 0 |
+| `lib/elementStyles.ts` | 146 | 1 | 1 | 0 |
+| `lib/elementEffects.ts` | 267 | 1 | 2 | 0 |
+| **Total** | **~2,680** | **~145** | **~30** | **1** |
+
+---
+
+## Best Practices
+
+### 1. Use Central Exports
+
+```typescript
+// Good - import from central index
+import { User, Project, Asset } from '@/types';
+
+// Avoid - importing from individual files for common types
+import { User } from '@/types/entities';
+import { Project } from '@/types/entities';
+```
+
+### 2. Extend Base Entity
+
+```typescript
+// Good - extend BaseEntity
+export interface NewEntity extends BaseEntity {
+  customField: string;
+}
+
+// Avoid - duplicating id/createdAt/updatedAt
+export interface NewEntity {
+  id: string;
+  createdAt: string;
+  // ...
+}
+```
+
+### 3. Use Const Assertions for Enums
+
+```typescript
+// Good - const assertion for type narrowing
+export const CANVAS_ELEMENT_TYPES = [...] as const;
+export type CanvasElementType = (typeof CANVAS_ELEMENT_TYPES)[number];
+
+// Works well with type guards
+function isCanvasElementType(value: string): value is CanvasElementType {
+  return CANVAS_ELEMENT_TYPES.includes(value as CanvasElementType);
+}
+```
+
+### 4. Component Props Interfaces
+
+```typescript
+// Good - clear interface name with Props suffix
+export interface CanvasElementProps {
+  element: CanvasElement;
+  isSelected: boolean;
+  onClick: (element: CanvasElement) => void;
+}
+
+// Use in component
+function CanvasElementComponent({ element, isSelected, onClick }: CanvasElementProps) {
+  // ...
+}
+```
+
+### 5. Generic Types for Reusability
+
+```typescript
+// Good - generic interfaces
+export interface EntitySliceState<T> {
+  data: T[];
+  loading: boolean;
+  count: number;
+}
+
+// Usage
+type UsersState = EntitySliceState<User>;
+type ProjectsState = EntitySliceState<Project>;
+```
+
+---
+
+## Related Documentation
+
+- [types-module.md](./types-module.md) - Older types documentation
+- [stores-module.md](./stores-module.md) - Redux state types usage
+- [factories-module.md](./factories-module.md) - Generic type usage in factories
+- [hooks-module.md](./hooks-module.md) - Hook interface definitions
+- [components-module.md](./components-module.md) - Component props types
diff --git a/frontend/docs/layouts-module.md b/frontend/docs/layouts-module.md
new file mode 100644
index 0000000..afa9b44
--- /dev/null
+++ b/frontend/docs/layouts-module.md
@@ -0,0 +1,601 @@
+# Frontend Layouts Module
+
+## Overview
+
+The Layouts module provides **page wrapper components** that handle authentication, authorization, navigation chrome, and styling for the application. Using Next.js's `getLayout` pattern, layouts are applied per-page rather than globally.
+
+**Location:** `frontend/src/layouts/`
+
+**Total Files:** 2 files (~262 LOC)
+
+---
+
+## Architecture
+
+```
+frontend/src/layouts/
+├── Authenticated.tsx   (243 LOC)  # Protected routes with full UI chrome
+└── Guest.tsx           (19 LOC)   # Public routes (login, register, etc.)
+
+Related Files:
+├── menuAside.ts        (42 LOC)   # Sidebar menu configuration
+├── menuNavBar.ts       (51 LOC)   # Top navbar menu configuration
+└── pages/_app.tsx      (324 LOC)  # getLayout pattern implementation
+```
+
+---
+
+## Layout Pattern (Next.js getLayout)
+
+### Pattern Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        _app.tsx                             │
+│  const getLayout = Component.getLayout || ((page) => page)  │
+│  return getLayout(<Component {...pageProps} />)             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Page Component                           │
+│  Page.getLayout = (page) => <Layout>{page}</Layout>         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Type Definition
+
+```typescript
+// In _app.tsx
+export type NextPageWithLayout<P = Record<string, unknown>, IP = P> = NextPage<P, IP> & {
+  getLayout?: (page: ReactElement) => ReactNode;
+};
+
+type AppPropsWithLayout = AppProps & {
+  Component: NextPageWithLayout;
+};
+```
+
+### Usage in _app.tsx
+
+```typescript
+function MyApp({ Component, pageProps }: AppPropsWithLayout) {
+  // Use the layout defined at the page level, if available
+  const getLayout = Component.getLayout || ((page) => page);
+
+  return (
+    <Provider store={store}>
+      <DownloadProvider>
+        {getLayout(
+          <>
+            <Head>...</Head>
+            <ErrorBoundary>
+              <Component {...pageProps} />
+            </ErrorBoundary>
+          </>
+        )}
+      </DownloadProvider>
+    </Provider>
+  );
+}
+```
+
+---
+
+## Layout Files
+
+### 1. LayoutAuthenticated (`Authenticated.tsx`)
+
+**Purpose:** Wrapper for protected routes requiring authentication and optional permission checking.
+
+**Lines:** 243 LOC
+
+#### Props Interface
+
+```typescript
+type Props = {
+  children: ReactNode;
+  permission?: string;           // Required permission for this page
+  minimal?: boolean;             // If true, render only auth check (no UI chrome)
+};
+```
+
+#### Features
+
+| Feature | Description |
+|---------|-------------|
+| JWT Validation | Client-side token decode and expiry check |
+| Auto-redirect | Redirects to `/login` if no valid token |
+| Permission Guard | Redirects to `/error` if permission missing |
+| Project Existence Check | Redirects to project creation for certain routes |
+| NavBar | Top navigation with search and user menu |
+| AsideMenu | Sidebar navigation menu |
+| FooterBar | Page footer |
+| Dark Mode | Applies dark mode styling |
+| Responsive | Mobile-friendly sidebar toggle |
+| Minimal Mode | Auth-only mode for presentations |
+
+#### Authentication Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    LayoutAuthenticated                      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │  Get Token from │
+                    │  Session/Local  │
+                    │    Storage      │
+                    └────────┬────────┘
+                              │
+                    ┌─────────▼─────────┐
+                    │   Token Valid?    │
+                    │  (JWT decode +    │
+                    │   expiry check)   │
+                    └────────┬──────────┘
+                              │
+              ┌───────────────┴───────────────┐
+              │ No                            │ Yes
+              ▼                               ▼
+    ┌─────────────────┐             ┌─────────────────┐
+    │  dispatch       │             │ Set axios       │
+    │  logoutUser()   │             │ Authorization   │
+    │  redirect to    │             │ header          │
+    │  /login         │             └────────┬────────┘
+    └─────────────────┘                       │
+                                    ┌─────────▼─────────┐
+                                    │ currentUser       │
+                                    │ loaded?           │
+                                    └────────┬──────────┘
+                                              │
+                              ┌───────────────┴───────────────┐
+                              │ No                            │ Yes
+                              ▼                               ▼
+                    ┌─────────────────┐             ┌─────────────────┐
+                    │ dispatch        │             │ Check           │
+                    │ findMe()        │             │ permissions     │
+                    └─────────────────┘             └────────┬────────┘
+                                                             │
+                                                   ┌─────────▼─────────┐
+                                                   │ Permission OK?    │
+                                                   └────────┬──────────┘
+                                                             │
+                                         ┌───────────────────┴────────────┐
+                                         │ No                             │ Yes
+                                         ▼                                ▼
+                               ┌─────────────────┐              ┌─────────────────┐
+                               │ redirect to     │              │ Render page     │
+                               │ /error          │              │ with layout     │
+                               └─────────────────┘              └─────────────────┘
+```
+
+#### Token Validation
+
+```typescript
+const isTokenValid = (tokenToCheck?: string | null) => {
+  if (!tokenToCheck) return false;
+
+  try {
+    const decoded = jwt.decode(tokenToCheck);
+    if (!decoded || typeof decoded !== 'object') return false;
+    if (typeof decoded.exp !== 'number') return true;  // No expiry = valid
+    return Date.now() / 1000 < decoded.exp;            // Check expiry
+  } catch (error) {
+    logger.error('Failed to decode auth token:', error);
+    return false;
+  }
+};
+```
+
+#### Routes Requiring Project
+
+Certain routes redirect to project creation if no projects exist:
+
+```typescript
+const ROUTES_REQUIRING_PROJECT = [
+  '/access_logs',
+  '/assets',
+  '/asset_variants',
+  '/presigned_url_requests',
+  '/project_audio_tracks',
+  '/project_memberships',
+  '/publish_events',
+  '/pwa_caches',
+  '/tour_pages',
+];
+```
+
+#### Constructor Fullscreen Mode
+
+The constructor page (`/constructor`) hides navigation chrome:
+
+```typescript
+const isConstructorFullscreen = router.pathname === '/constructor';
+
+// When true:
+// - NavBar is hidden
+// - AsideMenu is hidden
+// - FooterBar is hidden
+// - No padding applied
+```
+
+#### Minimal Mode
+
+For presentations that need auth but no UI chrome:
+
+```typescript
+if (minimal) {
+  return <>{children}</>;
+}
+```
+
+#### Loading State
+
+Shows loading spinner while auth is being checked:
+
+```typescript
+if (!isAuthChecked) {
+  return (
+    <div className={`${darkMode ? 'dark' : ''} ...`}>
+      <div className='animate-spin rounded-full h-8 w-8 ...'></div>
+      <p>Loading...</p>
+    </div>
+  );
+}
+```
+
+#### Layout Structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         NavBar                              │
+│  [☰ Mobile] [Desktop Menu] [Search] [User Menu] [Logout]   │
+└─────────────────────────────────────────────────────────────┘
+┌──────────────┬──────────────────────────────────────────────┐
+│              │                                              │
+│   AsideMenu  │                                              │
+│              │              Page Content                    │
+│  - Dashboard │              (children)                      │
+│  - Projects  │                                              │
+│  - Users     │                                              │
+│  - Profile   │                                              │
+│  - Swagger   │                                              │
+│              │                                              │
+└──────────────┴──────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│                        FooterBar                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 2. LayoutGuest (`Guest.tsx`)
+
+**Purpose:** Simple wrapper for public pages without authentication.
+
+**Lines:** 19 LOC
+
+#### Props Interface
+
+```typescript
+type Props = {
+  children: ReactNode;
+};
+```
+
+#### Features
+
+| Feature | Description |
+|---------|-------------|
+| Dark Mode | Applies dark mode styling from Redux |
+| Background Color | Applies theme background color |
+| No Auth | No authentication required |
+
+#### Implementation
+
+```typescript
+export default function LayoutGuest({ children }: Props) {
+  const darkMode = useAppSelector((state) => state.style.darkMode);
+  const bgColor = useAppSelector((state) => state.style.bgLayoutColor);
+
+  return (
+    <div className={darkMode ? 'dark' : ''}>
+      <div className={`${bgColor} dark:bg-slate-800 dark:text-slate-100`}>
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Menu Configuration
+
+### Aside Menu (`menuAside.ts`)
+
+Sidebar navigation items:
+
+```typescript
+const menuAside: MenuAsideItem[] = [
+  {
+    href: '/dashboard',
+    icon: icon.mdiViewDashboardOutline,
+    label: 'Dashboard',
+  },
+  {
+    href: '/projects/projects-list',
+    label: 'Projects',
+    icon: icon.mdiFolder,
+    permissions: 'READ_PROJECTS',      // Permission-gated
+  },
+  {
+    href: '/element-type-defaults',
+    label: 'Element Defaults',
+    icon: icon.mdiPaletteSwatch,
+    permissions: 'READ_PAGE_ELEMENTS',
+  },
+  {
+    href: '/users/users-list',
+    label: 'Users',
+    icon: icon.mdiAccountGroup,
+    permissions: 'READ_USERS',
+  },
+  {
+    href: '/profile',
+    label: 'Profile',
+    icon: icon.mdiAccountCircle,
+  },
+  {
+    href: swaggerDocsUrl,
+    target: '_blank',                   // Opens in new tab
+    label: 'Swagger',
+    icon: icon.mdiFileCode,
+    permissions: 'READ_API_DOCS',
+  },
+];
+```
+
+### NavBar Menu (`menuNavBar.ts`)
+
+Top navigation items:
+
+```typescript
+const menuNavBar: MenuNavBarItem[] = [
+  {
+    isCurrentUser: true,               // User dropdown
+    menu: [
+      { icon: mdiAccount, label: 'My Profile', href: '/profile' },
+      { isDivider: true },
+      { icon: mdiLogout, label: 'Log Out', isLogout: true },
+    ],
+  },
+  {
+    icon: mdiThemeLightDark,
+    label: 'Light/Dark',
+    isDesktopNoLabel: true,
+    isToggleLightDark: true,           // Dark mode toggle
+  },
+  {
+    icon: mdiLogout,
+    label: 'Log out',
+    isDesktopNoLabel: true,
+    isLogout: true,
+  },
+];
+
+// Additional export for web pages (currently empty)
+export const webPagesNavBar = [];
+```
+
+---
+
+## Usage Examples
+
+### Basic Authenticated Page
+
+```typescript
+// pages/users/users-list.tsx
+import LayoutAuthenticated from '../../layouts/Authenticated';
+
+function UsersListPage() {
+  return (
+    <SectionMain>
+      <h1>Users</h1>
+      {/* page content */}
+    </SectionMain>
+  );
+}
+
+UsersListPage.getLayout = function getLayout(page: ReactElement) {
+  return (
+    <LayoutAuthenticated permission='READ_USERS'>
+      {page}
+    </LayoutAuthenticated>
+  );
+};
+
+export default UsersListPage;
+```
+
+### Minimal Auth for Presentations
+
+```typescript
+// pages/p/[projectSlug]/stage.tsx
+import LayoutAuthenticated from '../../../layouts/Authenticated';
+
+function StagePresentation() {
+  return <RuntimePresentation mode="stage" />;
+}
+
+StagePresentation.getLayout = function getLayout(page: ReactElement) {
+  return (
+    <LayoutAuthenticated permission='READ_TOUR_PAGES' minimal>
+      {page}
+    </LayoutAuthenticated>
+  );
+};
+```
+
+### Public Page with Guest Layout
+
+```typescript
+// pages/login.tsx
+import LayoutGuest from '../layouts/Guest';
+
+function Login() {
+  return (
+    <SectionMain>
+      <LoginForm />
+    </SectionMain>
+  );
+}
+
+Login.getLayout = function getLayout(page: ReactElement) {
+  return <LayoutGuest>{page}</LayoutGuest>;
+};
+
+export default Login;
+```
+
+### Public Page (Production Presentation)
+
+```typescript
+// pages/p/[projectSlug]/index.tsx
+import LayoutGuest from '../../../layouts/Guest';
+
+function ProductionPresentation() {
+  return <RuntimePresentation mode="production" />;
+}
+
+ProductionPresentation.getLayout = function getLayout(page: ReactElement) {
+  return <LayoutGuest>{page}</LayoutGuest>;
+};
+```
+
+---
+
+## Page Layout Mapping
+
+| Route Pattern | Layout | Permission | Mode |
+|---------------|--------|------------|------|
+| `/login` | Guest | - | Public |
+| `/verify-email` | Guest | - | Public |
+| `/password-reset` | Guest | - | Public |
+| `/terms-of-use` | Guest | - | Public |
+| `/p/[slug]` | Guest | - | Public presentation |
+| `/p/[slug]/stage` | Authenticated | `READ_TOUR_PAGES` | Minimal (stage preview) |
+| `/dashboard` | Authenticated | - | Full chrome |
+| `/profile` | Authenticated | - | Full chrome |
+| `/constructor` | Authenticated | - | Fullscreen (no chrome) |
+| `/users/*` | Authenticated | `READ/CREATE/UPDATE_USERS` | Full chrome |
+| `/roles/*` | Authenticated | `READ/CREATE/UPDATE_ROLES` | Full chrome |
+| `/projects/*` | Authenticated | `READ/CREATE/UPDATE_PROJECTS` | Full chrome |
+| `/assets/*` | Authenticated | `READ/CREATE/UPDATE_ASSETS` | Full chrome |
+| `/tour_pages/*` | Authenticated | `READ/CREATE/UPDATE_TOUR_PAGES` | Full chrome |
+| `/element-type-defaults` | Authenticated | `READ_PAGE_ELEMENTS` | Full chrome |
+
+---
+
+## Redux State Dependencies
+
+Both layouts depend on Redux style state:
+
+```typescript
+// In styleSlice.ts
+interface StyleState {
+  darkMode: boolean;           // Dark mode toggle
+  bgLayoutColor: string;       // Background color class
+  // ...
+}
+
+// Usage in layouts
+const darkMode = useAppSelector((state) => state.style.darkMode);
+const bgColor = useAppSelector((state) => state.style.bgLayoutColor);
+```
+
+---
+
+## Related Components
+
+### NavBar Component
+
+Top navigation bar with:
+- Mobile hamburger menu toggle
+- Desktop menu button
+- Search component
+- User menu items
+
+### AsideMenu Component
+
+Sidebar navigation with:
+- Permission-filtered menu items
+- Mobile/desktop responsive
+- Collapsible on route change
+
+### FooterBar Component
+
+Page footer with copyright/credits.
+
+### Search Component
+
+Global search functionality in NavBar.
+
+---
+
+## Best Practices
+
+### 1. Always Define getLayout
+
+```typescript
+// Every page should define its layout
+Page.getLayout = function getLayout(page: ReactElement) {
+  return <LayoutAuthenticated permission='...'>{page}</LayoutAuthenticated>;
+};
+```
+
+### 2. Use Specific Permissions
+
+```typescript
+// Good - specific permission
+<LayoutAuthenticated permission='UPDATE_USERS'>
+
+// Avoid - too broad
+<LayoutAuthenticated>  // No permission check
+```
+
+### 3. Use Minimal Mode for Presentations
+
+```typescript
+// Presentations need auth but no UI chrome
+<LayoutAuthenticated permission='READ_TOUR_PAGES' minimal>
+```
+
+### 4. Guest Layout for Public Pages
+
+```typescript
+// Public pages should use LayoutGuest
+<LayoutGuest>{page}</LayoutGuest>
+```
+
+---
+
+## File Inventory
+
+| File | LOC | Purpose |
+|------|-----|---------|
+| `Authenticated.tsx` | 243 | Protected route wrapper with auth, permissions, UI chrome |
+| `Guest.tsx` | 19 | Public route wrapper with dark mode support |
+| `menuAside.ts` | 42 | Sidebar menu configuration |
+| `menuNavBar.ts` | 51 | Top navbar menu configuration |
+| **Total** | **355** | |
+
+---
+
+## Related Documentation
+
+- [pages-module.md](./pages-module.md) - Page structure and getLayout usage
+- [helpers-module.md](./helpers-module.md) - hasPermission function
+- [stores-module.md](./stores-module.md) - authSlice and styleSlice
+- [types-module.md](./types-module.md) - Permission types
diff --git a/frontend/docs/lib-module.md b/frontend/docs/lib-module.md
new file mode 100644
index 0000000..4be00e5
--- /dev/null
+++ b/frontend/docs/lib-module.md
@@ -0,0 +1,1351 @@
+# Lib Module
+
+## Overview
+
+The lib module provides **utility libraries and helper functions** used throughout the frontend application. These are pure functions and classes that encapsulate domain-specific logic, separated from React components and Redux state management.
+
+**Location:** `frontend/src/lib/`
+
+**Statistics:**
+- **23 files** (~5,608 LOC total)
+- **2 subdirectories** (offline, offlineDb)
+- **8 main categories**: Asset Management, Element Utilities, Navigation/Preload, Media Utilities, Audio Utilities, Fonts, General Utilities, Offline/PWA
+
+---
+
+## Architecture Diagram
+
+```
+frontend/src/lib/
+├── Core Asset Management
+│   ├── assetUrl.ts              # Presigned URL management (~405 LOC)
+│   └── imagePreDecode.ts        # Image pre-decoding (~202 LOC)
+│
+├── UI Adaptivity & Element Utilities
+│   ├── canvasScale.ts           # Canvas units & responsive scaling (~219 LOC)
+│   ├── elementDefaults.ts       # Element defaults & type guards (~707 LOC)
+│   ├── elementStyles.ts         # CSS style building with canvas units (~345 LOC)
+│   ├── elementEffects.ts        # Animation/interaction/audio effects (~374 LOC)
+│   ├── gallerySectionStyles.ts  # Gallery section styling (~544 LOC)
+│   └── constructorHelpers.ts    # Constructor page utilities (~279 LOC)
+│
+├── Navigation & Preloading
+│   ├── navigationHelpers.ts     # Page navigation utilities (~237 LOC)
+│   ├── extractPageLinks.ts      # Page link extraction (~182 LOC)
+│   ├── tourFlowHelpers.ts       # Tour routing utilities (~118 LOC)
+│   └── resolveSlideTransition.ts # Slide transition cascade resolver (~150 LOC)
+│
+├── Media Utilities
+│   ├── mediaDuration.ts         # Duration probing (~119 LOC)
+│   └── mediaHelpers.ts          # Duration formatting (~158 LOC)
+│
+├── Audio Utilities
+│   └── backgroundAudioController.ts # Audio ducking singleton (~81 LOC)
+│
+├── Font Configuration
+│   └── fonts.ts                 # Font options & utilities (~110 LOC)
+│
+├── General Utilities
+│   ├── logger.ts                # Structured logging (~163 LOC)
+│   ├── parseJson.ts             # Safe JSON parsing (~89 LOC)
+│   ├── slugHelpers.ts           # URL slug utilities (~88 LOC)
+│   └── queryClient.ts           # React Query client (~155 LOC)
+│
+├── offline/                     # PWA download management
+│   ├── StorageManager.ts        # Cache API + IndexedDB (~294 LOC)
+│   ├── DownloadManager.ts       # Download queue (~591 LOC)
+│   └── DownloadEventBus.ts      # Progress events (~188 LOC)
+│
+└── offlineDb/                   # IndexedDB persistence
+    ├── schema.ts                # Dexie.js schema (~41 LOC)
+    └── OfflineDbManager.ts      # CRUD operations (~342 LOC)
+```
+
+---
+
+## Module Categories
+
+### 1. Core Asset Management
+
+#### assetUrl.ts
+**Purpose:** Resolves relative asset paths to playback URLs with presigned S3 support.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `resolveAssetPlaybackUrl` | Function | Main URL resolver (handles all URL types) |
+| `queuePresignedUrls` | Function | Batch presigned URL fetching |
+| `queuePresignedUrl` | Function | Single presigned URL fetching |
+| `getPresignedUrl` | Function | Synchronous cache lookup |
+| `markPresignedUrlsVerified` | Function | Enable direct S3 access |
+| `disablePresignedUrls` | Function | Fall back to proxy mode |
+| `arePresignedUrlsDisabled` | Function | Check if presigned URLs disabled |
+| `extractStoragePath` | Function | Extract storage path from URL |
+| `isRelativeStoragePath` | Function | Check if path is relative |
+| `flushPresignedUrlQueue` | Function | Flush pending batch |
+| `clearPresignedUrlCache` | Function | Clear presigned cache |
+| `setupPresignedUrlInterceptor` | Function | Setup Axios interceptor for CORS detection |
+
+**URL Resolution Logic:**
+```typescript
+export const resolveAssetPlaybackUrl = (value?: string): string => {
+  const normalized = String(value || '').trim();
+  if (!normalized) return '';
+
+  // Data and blob URLs pass through
+  if (normalized.startsWith('data:') || normalized.startsWith('blob:'))
+    return normalized;
+
+  // Already an API file download URL
+  if (normalized.startsWith('/api/file/download')) return normalized;
+
+  // File download path (prepend API base)
+  if (normalized.startsWith('/file/download'))
+    return `${baseURLApi}${normalized}`;
+
+  // Full URLs pass through
+  if (normalized.startsWith('http://') || normalized.startsWith('https://'))
+    return normalized;
+
+  // Relative path - check presigned URL cache first
+  const presigned = getPresignedUrl(normalized);
+  if (presigned) return presigned;
+
+  // Fallback to backend proxy
+  return `${baseURLApi}/file/download?privateUrl=${encodeURIComponent(normalized)}`;
+};
+```
+
+**Presigned URL Batching:**
+```typescript
+// Batch queue for efficient presigned URL requests
+const BATCH_DELAY_MS = 10; // Small delay to batch concurrent requests
+const PRESIGN_TTL_MS = 60 * 60 * 1000; // 1 hour TTL
+const CACHE_BUFFER_MS = 5 * 60 * 1000; // Refresh 5 min before expiry
+
+// Usage: Queue multiple URLs for batch presigning
+const presignedUrls = await queuePresignedUrls([
+  'assets/video1.mp4',
+  'assets/image1.jpg',
+  'assets/audio1.mp3',
+]);
+```
+
+---
+
+#### imagePreDecode.ts
+**Purpose:** Pre-decode images before display to prevent white flashes during transitions.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `decodeImage` | Function | Decode single image |
+| `decodeImages` | Function | Decode multiple images in parallel |
+| `extractPageImageUrls` | Function | Extract all image URLs from page |
+| `waitForPageImages` | Function | Wait for all page images to decode |
+
+**Usage Pattern:**
+```typescript
+// Before page transition - ensure images are decoded
+await waitForPageImages(targetPage, 2000, {
+  getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,
+  preloadedUrls: preloadOrchestrator.preloadedUrls,
+});
+
+// Now safe to switch - no white flash
+setActivePage(targetPage);
+```
+
+---
+
+### 2. Element Utilities
+
+#### elementDefaults.ts
+**Purpose:** Single source of truth for UI element default values, creation, and merging.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `createDefaultElement` | Function | Create new element with defaults |
+| `mergeElementWithDefaults` | Function | Merge element with project/global defaults |
+| `buildElementSettings` | Function | Build JSON for database storage |
+| `parseElementSettings` | Function | Parse JSON from database |
+| `createDefaultGalleryCard` | Function | Create default gallery card |
+| `createDefaultCarouselSlide` | Function | Create default carousel slide |
+| `normalizeGalleryCard` | Function | Normalize gallery card properties |
+| `normalizeCarouselSlide` | Function | Normalize carousel slide properties |
+| `normalizeAppearDelaySec` | Function | Normalize appear delay value |
+| `normalizeAppearDurationSec` | Function | Normalize appear duration value |
+| `isElementFlagEnabled` | Function | Strictly parse boolean feature flags stored in element JSON |
+| `findDefaultOpenInfoPanelElements` | Function | Return all enabled Info Panels configured with `infoPanelOpenByDefault` |
+| `createLocalId` | Function | Generate unique local ID |
+| `ELEMENT_TYPE_LABELS` | Object | Display labels for element types |
+| `TYPE_SPECIFIC_DEFAULTS` | Object | Type-specific default values |
+| `getNavigationButtonLabel` | Function | Get navigation button label |
+| `getNavigationButtonKind` | Function | Get navigation button kind |
+| `getNavigationTypeFromKind` | Function | Get navigation type from kind |
+
+**Element Type Detection (Type Guards):**
+```typescript
+// Single source of truth for element type detection
+export const isNavigationElementType = (type: string): type is 'navigation_next' | 'navigation_prev' =>
+  type === 'navigation_next' || type === 'navigation_prev';
+
+export const isTooltipElementType = (type: string): type is 'tooltip' =>
+  type === 'tooltip';
+
+export const isDescriptionElementType = (type: string): type is 'description' =>
+  type === 'description';
+
+export const isGalleryElementType = (type: string): type is 'gallery' =>
+  type === 'gallery';
+
+export const isCarouselElementType = (type: string): type is 'carousel' =>
+  type === 'carousel';
+
+export const isMediaElementType = (type: string): type is 'video_player' | 'audio_player' =>
+  type === 'video_player' || type === 'audio_player';
+
+export const isVideoPlayerElementType = (type: string): type is 'video_player' =>
+  type === 'video_player';
+
+export const isAudioPlayerElementType = (type: string): type is 'audio_player' =>
+  type === 'audio_player';
+
+export const isLogoElementType = (type: string): type is 'logo' =>
+  type === 'logo';
+
+export const isSpotElementType = (type: string): type is 'spot' =>
+  type === 'spot';
+
+export const isPopupElementType = (type: string): type is 'popup' =>
+  type === 'popup';
+```
+
+**Default Values by Type:**
+```typescript
+export const TYPE_SPECIFIC_DEFAULTS: Partial<Record<CanvasElementType, Partial<CanvasElement>>> = {
+  navigation_next: {
+    navLabel: 'Forward',
+    navType: 'forward',
+    navDisabled: false,
+    iconUrl: '',
+    transitionReverseMode: 'auto_reverse',
+  },
+  tooltip: {
+    iconUrl: '',
+    tooltipTitle: 'Tooltip title',
+    tooltipText: 'Tooltip text',
+  },
+  description: {
+    descriptionTitle: 'TITLE',
+    descriptionText: '',
+    descriptionTitleFontSize: '24px',
+    descriptionTextFontSize: '16px',
+    // ... more properties
+  },
+  video_player: {
+    mediaUrl: '',
+    mediaAutoplay: true,
+    mediaLoop: true,
+    mediaMuted: true,
+  },
+  // ... more types
+};
+```
+
+---
+
+#### canvasScale.ts
+**Purpose:** Canvas scale utilities for responsive UI. Provides the foundation for the UI Adaptivity System.
+
+> **See:** [UI Adaptivity System](ui-adaptivity-system.md) for complete documentation.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `calculateCanvasScale` | Function | Calculate scale factor for viewport |
+| `toCU` | Function | Convert design pixels to `calc()` expression |
+| `isLegacyUnit` | Function | Check if value uses legacy units (px/vw/vh/rem) |
+| `normalizeToCanvasUnits` | Function | Convert legacy units to canvas units |
+| `getCanvasCssVars` | Function | Generate CSS custom properties object |
+| `vwToDesignPx` | Function | Convert vw to design pixels |
+| `vhToDesignPx` | Function | Convert vh to design pixels |
+| `remToDesignPx` | Function | Convert rem to design pixels |
+
+**Canvas Units (--cu):**
+```typescript
+// toCU converts design pixels to CSS calc expression
+toCU(24)  // → "calc(24 * var(--cu, 1px))"
+toCU(0)   // → "0"
+
+// At 1920×1080 on 1920×1080 viewport: --cu = 1px
+// At 3840×2160 viewport: --cu = 2px (elements 2x larger)
+// At 960×540 viewport: --cu = 0.5px (elements half size)
+```
+
+**Scale Calculation:**
+```typescript
+// Fit design canvas within viewport
+const scale = calculateCanvasScale(
+  window.innerWidth,   // viewportWidth
+  window.innerHeight,  // viewportHeight
+  1920,                // designWidth
+  1080,                // designHeight
+);
+// Returns: min(viewportW/designW, viewportH/designH) clamped to [0.1, 4.0]
+```
+
+**CSS Custom Properties:**
+```typescript
+const cssVars = getCanvasCssVars(scale, 1920, 1080);
+// Returns:
+// {
+//   '--design-width': '1920',
+//   '--design-height': '1080',
+//   '--canvas-scale': '0.75',
+//   '--cu': 'calc(1px * 0.75)',
+// }
+```
+
+---
+
+#### elementStyles.ts
+**Purpose:** Unified types and utilities for UI element CSS styling with automatic canvas unit conversion.
+
+> **See:** [UI Adaptivity System](ui-adaptivity-system.md) for canvas unit documentation.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `buildElementStyle` | Function | Build React CSSProperties from element |
+| `normalizePixelValue` | Function | Normalize value to canvas units |
+| `normalizeViewportWidth` | Function | Convert vw to canvas units |
+| `normalizeViewportHeight` | Function | Convert vh to canvas units |
+| `ELEMENT_STYLE_PROPS` | Array | List of CSS property names |
+| `ElementStyleProperties` | Interface | TypeScript interface for styles |
+
+**Supported CSS Properties:**
+```typescript
+export const ELEMENT_STYLE_PROPS = [
+  'width', 'height', 'minWidth', 'maxWidth', 'minHeight', 'maxHeight',
+  'margin', 'padding', 'gap',
+  'fontSize', 'lineHeight', 'fontWeight', 'fontFamily',
+  'border', 'borderRadius', 'opacity', 'boxShadow',
+  'display', 'position', 'justifyContent', 'alignItems', 'textAlign',
+  'zIndex', 'backgroundColor', 'color',
+] as const;
+```
+
+**Canvas Unit Normalization:**
+
+The module automatically normalizes numeric values to **canvas units (--cu)** for responsive scaling:
+
+| Property | Conversion | Example |
+|----------|------------|---------|
+| width, minWidth, maxWidth | Canvas units | `"200"` → `"calc(200 * var(--cu, 1px))"` |
+| height, minHeight, maxHeight | Canvas units | `"100"` → `"calc(100 * var(--cu, 1px))"` |
+| borderRadius, fontSize | Canvas units | `"12"` → `"calc(12 * var(--cu, 1px))"` |
+
+**Legacy Unit Conversion:**
+| Input | Output |
+|-------|--------|
+| `"24px"` | `"calc(24 * var(--cu, 1px))"` |
+| `"50vw"` | `"calc(960 * var(--cu, 1px))"` (50% of 1920) |
+| `"25vh"` | `"calc(270 * var(--cu, 1px))"` (25% of 1080) |
+| `"1.5rem"` | `"calc(24 * var(--cu, 1px))"` (1.5 × 16) |
+
+**Edge Cases Handled:**
+| Input | Output | Reason |
+|-------|--------|--------|
+| `"0"` | `"0"` | Zero → no unit needed |
+| `"var(--cu)"` | preserved | Already uses canvas units |
+| `"calc(...)"` | preserved | CSS function → preserve |
+| `"10px 20px"` | preserved | Complex → preserve |
+
+**Note:** `border` is NOT auto-normalized - it's a complex shorthand value (e.g., `"2px solid #ccc"`).
+
+**Usage:**
+```typescript
+import { toCU } from './canvasScale';
+
+// Build React CSSProperties from element data
+const style = buildElementStyle({
+  width: '200',       // → "calc(200 * var(--cu, 1px))"
+  height: '100',      // → "calc(100 * var(--cu, 1px))"
+  borderRadius: '12', // → "calc(12 * var(--cu, 1px))"
+  opacity: '0.5',
+  display: 'flex',
+  zIndex: '10',
+});
+
+// Or use toCU directly
+const buttonStyle = {
+  fontSize: toCU(16),
+  padding: `${toCU(8)} ${toCU(16)}`,
+};
+```
+
+### Opacity Percent Helpers
+
+`frontend/src/lib/opacityPercent.ts` centralizes conversion between author UI
+percent inputs and stored CSS opacity values:
+
+| Helper | Purpose |
+|--------|---------|
+| `opacityToPercentInput(value)` | Displays stored `0..1` opacity as clamped `0..100` percent text |
+| `percentInputToOpacityValue(value)` | Converts author `0..100` percent input back to a stored `0..1` string |
+| `percentInputToOpacityNumber(value)` | Converts author percent input to a numeric `0..1` value for system UI controls |
+
+Element style/effects forms and constructor system-control opacity fields use
+these helpers so all opacity inputs clamp consistently.
+Element opacity is part of the shared element style property list, so global
+and project element defaults cascade into newly created constructor elements the
+same way as width, padding, border radius, and other style defaults.
+
+---
+
+#### gallerySectionStyles.ts
+**Purpose:** Unified types and utilities for gallery element section styling with CSS inheritance support.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `buildGalleryHeaderStyle` | Function | Build CSS for gallery header |
+| `buildGalleryTitleStyle` | Function | Build CSS for gallery title |
+| `buildGallerySpanStyle` | Function | Build CSS for info spans |
+| `buildGallerySpanGridStyle` | Function | Build CSS for span grid |
+| `buildGalleryCardStyle` | Function | Build CSS for gallery cards |
+| `buildGalleryCardTitleStyle` | Function | Build CSS for card title overlay |
+| `buildGalleryCardGridStyle` | Function | Build CSS for card grid |
+| `getGalleryGridColumns` | Function | Get grid columns with fallback |
+| `GALLERY_SECTION_DEFAULTS` | Object | Default styles per section |
+| `GALLERY_SECTION_STYLE_PROPS` | Array | All gallery style property names |
+
+**CSS Inheritance:**
+
+Gallery sections support CSS inheritance from the wrapper element. Inheritable properties (color, fontSize, fontWeight, lineHeight) are only applied to child sections if explicitly set, allowing values to cascade from General Element Styles.
+
+```typescript
+// applyIfSet - only applies value if set (allows CSS inheritance)
+applyIfSet(style, 'color', element.galleryHeaderColor);
+applyIfSet(style, 'fontSize', element.galleryHeaderFontSize, normalizeRemValue);
+
+// applyWithDefault - applies value or falls back to default (blocks inheritance)
+applyWithDefault(style, 'padding', element.galleryHeaderPadding, defaults.padding, normalizeRemValue);
+```
+
+**Unit Normalization (rem and px):**
+
+Gallery styles use `rem` units for typography/spacing and `px` for dimensions:
+
+| Property | Unit | Default | Example |
+|----------|------|---------|---------|
+| fontSize | rem | `"1.5rem"` | `"0.875"` → `"0.875rem"` |
+| padding | rem | `"0.5rem 0.75rem"` | `"0.5"` → `"0.5rem"` |
+| borderRadius | rem | `"0.5rem"` | `"0.75"` → `"0.75rem"` |
+| gap | rem | `"0.5rem"` | `"1"` → `"1rem"` |
+| galleryHeaderHeight | px | (none) | `"200"` → `"200px"` |
+| galleryHeaderMinHeight | px | (none) | `"150"` → `"150px"` |
+| galleryHeaderMaxHeight | px | (none) | `"400"` → `"400px"` |
+| galleryCardHeight | px | (none) | `"200"` → `"200px"` |
+| galleryCardMinHeight | px | `"40px"` | `"150"` → `"150px"` |
+| galleryHeaderWidth | (none) | (none) | Preserved (e.g., `"100%"`) |
+| galleryCardWidth | (none) | (none) | Preserved (e.g., `"auto"`) |
+| galleryCardAspectRatio | (none) | `"4/3"` | Preserved (e.g., `"16/9"`) |
+
+**Section Defaults:**
+```typescript
+export const GALLERY_SECTION_DEFAULTS = {
+  header: { fontSize: '1.5rem', fontWeight: '700', padding: '0.25rem 0.5rem', textAlign: 'center' },
+  title: { backgroundColor: '#fefce8', color: '#1e293b', fontSize: '0.875rem', textAlign: 'center', ... },
+  span: { backgroundColor: '#334155', color: '#fef3c7', fontSize: '0.75rem', textAlign: 'center', ... },
+  card: { borderRadius: '0.5rem' },
+  wrapper: { backgroundColor: 'rgba(0,0,0,0.6)', padding: '0.75rem', ... },
+};
+```
+
+---
+
+#### elementEffects.ts
+**Purpose:** Animation and interaction effect utilities for UI elements.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `buildTransitionStyle` | Function | Build base transition CSS |
+| `buildHoverStyle` | Function | Build hover state CSS |
+| `buildFocusStyle` | Function | Build focus state CSS |
+| `buildActiveStyle` | Function | Build active/press state CSS |
+| `buildAppearAnimationStyle` | Function | Build appear animation CSS |
+| `hasHoverEffects` | Function | Check if hover effects configured |
+| `hasAudioEffects` | Function | Check if audio effects configured |
+| `hasAnyEffects` | Function | Check if any effects configured (includes audio) |
+| `EFFECT_PROPS` | Array | List of effect property names |
+
+**Appear Animation Types:**
+```typescript
+export type AppearAnimationType =
+  | ''
+  | 'fade'
+  | 'slide-up'
+  | 'slide-down'
+  | 'slide-left'
+  | 'slide-right'
+  | 'scale';
+```
+
+**Effect Properties:**
+```typescript
+export interface ElementEffectProperties {
+  // Appear animation
+  appearAnimation?: AppearAnimationType;
+  appearAnimationDuration?: string;
+  appearAnimationEasing?: string;
+  // Hover effects
+  hoverScale?: string;
+  hoverOpacity?: string;
+  hoverBackgroundColor?: string;
+  hoverColor?: string;
+  hoverBoxShadow?: string;
+  hoverTransitionDuration?: string;
+  // Focus effects
+  focusScale?: string;
+  focusOpacity?: string;
+  focusOutline?: string;
+  focusBoxShadow?: string;
+  // Active/press effects
+  activeScale?: string;
+  activeOpacity?: string;
+  activeBackgroundColor?: string;
+  // Hover Reveal effects
+  hoverReveal?: boolean;
+  hoverRevealInitialOpacity?: string;
+  hoverRevealTargetOpacity?: string;
+  hoverRevealDuration?: string;
+  hoverRevealDelay?: string;
+  hoverRevealPersist?: boolean;
+  hoverPersistOnClick?: boolean;
+  // Audio effects
+  hoverAudioUrl?: string;      // Audio to play on hover start
+  clickAudioUrl?: string;      // Audio to play on click/active
+  audioVolume?: string;        // Volume 0-1 as string
+}
+```
+
+**Important: Animation & Effects Wrapper Pattern**
+
+CSS animations with `animation-fill-mode: forwards` lock animated properties (opacity, transform), blocking CSS transitions for hover/focus/active states. To solve this, `CanvasElement` and `RuntimeElement` use a **wrapper div pattern**:
+
+```
+Outer div: positioning + appear animation
+  └── Inner div: hover/focus/active effects (independent from animation)
+```
+
+This allows interactive effects to work without being blocked by the animation's fill mode. The animation stays on the outer div to maintain the positioning CSS hack (existing element positions depend on the animation's transform).
+
+---
+
+#### constructorHelpers.ts
+**Purpose:** Utility functions for the constructor (tour builder) page.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `getAssetLabel` | Function | Format asset display label |
+| `getAssetSourceValue` | Function | Get asset storage key |
+| `buildAssetOptions` | Function | Build dropdown options for asset type |
+| `buildBackgroundImageOptions` | Function | Filter background images |
+| `buildTransitionVideoOptions` | Function | Filter transition videos |
+| `buildIconAssetOptions` | Function | Filter icon assets |
+| `getElementButtonTitle` | Function | Get element menu title |
+| `extractNumericValue` | Function | Extract number from CSS value |
+
+**Asset Options Building:**
+```typescript
+// Build options for a specific asset type
+const videoOptions = buildAssetOptions(assets, 'video');
+const audioOptions = buildAudioAssetOptions(assets);
+const backgroundOptions = buildBackgroundImageOptions(assets);
+
+// Transition videos prefer assets marked with type='transition'
+const transitionOptions = buildTransitionVideoOptions(assets);
+// Falls back to [TRANSITION] tag in name, then all videos
+```
+
+---
+
+### 3. Navigation & Preloading
+
+#### navigationHelpers.ts
+**Purpose:** Shared utilities for page navigation in RuntimePresentation and constructor.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `resolveNavigationTarget` | Function | Resolve target page from element |
+| `isBackNavigation` | Function | Check if navigation is backward |
+| `getNavigationDirection` | Function | Get 'back' or 'forward' |
+| `isTransitionBlocking` | Function | Check if transition blocks navigation |
+| `hasPlayableTransition` | Function | Check if transition can play |
+
+**Navigation Resolution:**
+```typescript
+// Resolve target page from element with navigation properties
+const target = resolveNavigationTarget(element, pages);
+// Returns: { page, pageId, transitionVideoUrl, isBack }
+
+// Check if navigation should be blocked during transition
+const blocked = isTransitionBlocking(transitionPhase, isBuffering);
+// true during: 'preparing', 'playing', 'reversing', or buffering
+```
+
+---
+
+#### extractPageLinks.ts
+**Purpose:** Extract synthetic page links and preload elements from tour pages' ui_schema_json.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `extractPageLinksAndElements` | Function | Extract links and elements for preloading |
+
+**Usage Pattern:**
+```typescript
+// Extract preload data from pages
+const { pageLinks, preloadElements } = extractPageLinksAndElements(pages);
+
+// Use with preload orchestrator
+const preloadOrchestrator = usePreloadOrchestrator({
+  pages,
+  pageLinks,
+  elements: preloadElements,
+  currentPageId,
+});
+```
+
+**Extracted Data:**
+1. **pageLinks** - Synthetic links for neighbor graph (enables preloading connected pages)
+2. **preloadElements** - Elements with asset URLs for preload queue
+
+---
+
+#### tourFlowHelpers.ts
+**Purpose:** Utilities for tour page routing and project handling.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `toRoutePath` | Function | Normalize value to valid route path |
+| `routeParts` | Function | Split route path into segments |
+| `compareRoutes` | Function | Compare routes for sorting |
+| `getProjectId` | Function | Extract project ID from various formats |
+| `getRows` | Function | Safe row extraction from API response |
+
+**Examples:**
+```typescript
+toRoutePath('my-page')           // '/my-page'
+toRoutePath('//double//slash')   // '/double/slash'
+toRoutePath('')                  // '/'
+
+routeParts('/my/page/path')      // ['my', 'page', 'path']
+
+getProjectId({ projectId: '123' })       // '123'
+getProjectId({ project: { id: '456' } }) // '456'
+```
+
+---
+
+#### resolveSlideTransition.ts
+**Purpose:** Cascade resolver for slide transitions in Gallery/Carousel elements. Resolves settings from page transitions with element-level override support.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `resolveSlideTransition` | Function | Resolve final slide transition settings with cascade |
+| `extractCarouselSlideOverride` | Function | Extract override from carousel element |
+| `extractGallerySlideOverride` | Function | Extract override from gallery element |
+
+**Cascade Order:**
+1. Element override (highest priority)
+2. Page transition settings (from `useTransitionSettings`)
+3. Hardcoded fallback: `{ type: 'fade', durationMs: 700, easing: 'ease-in-out', overlayColor: '#000000' }`
+
+**Types:**
+```typescript
+interface SlideTransitionOverride {
+  type?: 'fade' | 'none' | '';
+  durationMs?: number | '';
+  easing?: EasingFunction | '';
+  overlayColor?: string;
+}
+
+interface ResolvedSlideTransition {
+  type: 'fade' | 'none';
+  durationMs: number;
+  easing: EasingFunction;
+  overlayColor: string;
+}
+```
+
+**Usage:**
+```typescript
+import {
+  resolveSlideTransition,
+  extractCarouselSlideOverride,
+} from '../lib/resolveSlideTransition';
+
+// In carousel component
+const slideSettings = resolveSlideTransition(
+  pageTransitionSettings,  // From useTransitionSettings hook
+  extractCarouselSlideOverride(element),
+);
+
+// slideSettings is now resolved with cascade
+// { type: 'fade', durationMs: 700, easing: 'ease-in-out', overlayColor: '#000000' }
+```
+
+**Key Behaviors:**
+- `'video'` page transition type maps to `'fade'` for slides (no video between slides)
+- Empty string (`''`) values cascade to lower priority settings
+- `durationMs` must be a positive number to override
+
+---
+
+### 4. Media Utilities
+
+#### mediaDuration.ts
+**Purpose:** Probe media duration from URL or File using HTML5 media elements.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `probeMediaDuration` | Function | Get duration, width, height from media |
+| `isVideoMimeType` | Function | Check if MIME type is video |
+| `isAudioMimeType` | Function | Check if MIME type is audio |
+
+**Usage:**
+```typescript
+// Probe video duration and dimensions
+const result = await probeMediaDuration('https://example.com/video.mp4', 'video');
+// Returns: { duration: 30.5, width: 1920, height: 1080 }
+```
+
+---
+
+#### mediaHelpers.ts
+**Purpose:** Media duration probing and formatting utilities.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `formatDurationNote` | Function | Format seconds to readable string |
+| `readMediaDuration` | Function | Read duration from URL |
+| `resolveDurationWithFallback` | Function | Duration with blob fallback |
+
+**Examples:**
+```typescript
+formatDurationNote(90)   // 'Duration: 1:30'
+formatDurationNote(45)   // 'Duration: 45s'
+formatDurationNote(null) // 'Duration: unknown'
+
+// Resolve with CORS fallback
+const duration = await resolveDurationWithFallback('assets/video.mp4', 'video');
+// First tries direct metadata loading
+// Falls back to blob download if CORS fails
+```
+
+---
+
+### 5. Audio Utilities
+
+#### presentationAudio.ts
+
+**Purpose:** Shared helper for detecting whether a presentation has any sound
+source. Used by runtime and constructor so the global mute/unmute button is
+shown consistently on every page when the presentation contains audio anywhere.
+
+**Rules checked:**
+- Page `background_audio_url`
+- Page `background_video_url` with `background_video_muted === false`
+- Element `hoverAudioUrl` / `clickAudioUrl`
+- Unmuted `audio_player` and `video_player` elements
+- Gallery video cards
+- Info Panel media-section video items
+
+Runtime calls `presentationHasAudio(pages)` for the currently loaded stage or
+production environment. Constructor calls `presentationHasAudio(pages,
+elements)` and also includes current unsaved background audio/video state so the
+sound button updates immediately while editing.
+
+#### backgroundAudioController.ts
+**Purpose:** Module-level singleton for coordinating background audio pause/resume when foreground audio (element hover/click sounds) plays. Implements audio ducking pattern.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `backgroundAudioController` | Object | Singleton controller instance |
+| `BackgroundAudioController` | Class | Controller class (for testing) |
+
+**API:**
+
+```typescript
+interface BackgroundAudioController {
+  register(audio: HTMLAudioElement | null): void;  // Register background audio element
+  notifyForegroundStart(): void;                    // Called when element audio starts
+  notifyForegroundEnd(): void;                      // Called when element audio ends
+  reset(): void;                                     // Clear all state
+}
+```
+
+**Usage:**
+```typescript
+import { backgroundAudioController } from '../lib/backgroundAudioController';
+
+// In CanvasBackground - register background audio element
+useEffect(() => {
+  backgroundAudioController.register(audioRef.current);
+  return () => backgroundAudioController.register(null);
+}, [audioRef.current]);
+
+// In useAudioEffects - notify when element audio plays
+audio.addEventListener('play', () => {
+  backgroundAudioController.notifyForegroundStart();
+});
+audio.addEventListener('ended', () => {
+  backgroundAudioController.notifyForegroundEnd();
+});
+```
+
+**Key Behaviors:**
+- **Reference Counting:** Tracks active foreground audio count to handle overlapping sounds
+- **Graceful Resume:** Only resumes background audio when all foreground audio ends
+- **Playback State Tracking:** Only pauses if audio was playing, only resumes if it was paused by controller
+- **Singleton Pattern:** Single instance shared across all components
+
+---
+
+### 6. Font Configuration
+
+#### fonts.ts
+**Purpose:** Centralized configuration for supported fonts in the platform.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `FONT_OPTIONS` | Array | List of available font options |
+| `getFontByKey` | Function | Get font option by unique key |
+| `getFontByValues` | Function | Get font by fontFamily + fontStretch |
+| `getFontKeyFromValues` | Function | Get font key from stored values |
+| `getFontStyle` | Function | Get CSS style object for font |
+
+**FontOption Interface:**
+```typescript
+interface FontOption {
+  key: string;           // Unique key (e.g., 'instrument-sans')
+  label: string;         // Display label for dropdowns
+  fontFamily: string;    // CSS font-family value
+  fontStretch?: string;  // Optional font-stretch for condensed variants
+}
+```
+
+**Available Fonts:**
+| Key | Label | Font Family |
+|-----|-------|-------------|
+| `instrument-sans` | Instrument Sans | 'Instrument Sans Variable', sans-serif |
+| `instrument-sans-condensed` | Instrument Sans Condensed | 'Instrument Sans Variable', sans-serif (75% stretch) |
+| `system-ui` | System UI | system-ui, sans-serif |
+| `arial` | Arial | Arial, sans-serif |
+| `helvetica` | Helvetica | Helvetica, sans-serif |
+| `georgia` | Georgia | Georgia, serif |
+| `times-new-roman` | Times New Roman | 'Times New Roman', serif |
+| `monospace` | Monospace | monospace |
+
+**Usage:**
+```typescript
+import { FONT_OPTIONS, getFontByKey, getFontStyle } from '@/lib/fonts';
+
+// Build dropdown options
+const options = FONT_OPTIONS.map(f => ({ value: f.key, label: f.label }));
+
+// Get font by key and apply style
+const font = getFontByKey('instrument-sans-condensed');
+if (font) {
+  const style = getFontStyle(font);
+  // { fontFamily: "'Instrument Sans Variable', sans-serif", fontStretch: '75%' }
+}
+```
+
+---
+
+### 7. General Utilities
+
+#### logger.ts
+**Purpose:** Lightweight, isomorphic logger for Next.js applications.
+
+**Features:**
+- Works in browser and SSR
+- Log levels: debug, info, warn, error
+- Development: colored console output
+- Production: structured JSON for log aggregation
+- Child loggers with additional context
+
+**Usage:**
+```typescript
+import { logger } from '@/lib/logger';
+
+logger.info('User logged in', { userId: '123' });
+logger.error('Failed to fetch data', error);
+
+// Child logger with persistent context
+const userLogger = logger.child({ userId: '123' });
+userLogger.info('Action performed'); // Includes userId automatically
+```
+
+**Configuration:**
+```typescript
+// Environment variables
+NEXT_PUBLIC_LOG_LEVEL=info  // debug, info, warn, error
+```
+
+---
+
+#### parseJson.ts
+**Purpose:** Safe JSON parsing utilities for values that may be strings or already parsed.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `parseJsonObject` | Function | Parse with fallback support |
+| `parseJsonField` | Function | Lenient parse (returns original on error) |
+| `getElementPreviewText` | Function | Extract preview text from content |
+
+**Usage:**
+```typescript
+// Safe parsing with fallback
+const schema = parseJsonObject<ConstructorSchema>(page.ui_schema_json, {});
+const settings = parseJsonObject<Settings>(value, { enabled: false });
+
+// Lenient parsing - returns original on error
+const content = parseJsonField(element.content_json);
+
+// Extract preview text for display
+const preview = getElementPreviewText(content);
+// Checks: title, text, subtitle, description, body, label, value
+```
+
+---
+
+#### slugHelpers.ts
+**Purpose:** URL slug generation and validation utilities.
+
+**Key Exports:**
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `sanitizeSlug` | Function | Sanitize string to valid slug |
+| `buildUniqueSlug` | Function | Generate unique slug avoiding collisions |
+| `isValidSlug` | Function | Validate slug format |
+| `slugPattern` | RegExp | Regex for valid slugs |
+
+**Examples:**
+```typescript
+sanitizeSlug('My Page Title')  // 'my-page-title'
+sanitizeSlug('Hello  World!')  // 'hello-world'
+
+const used = new Set(['my-page', 'my-page-2']);
+buildUniqueSlug('my-page', used)  // 'my-page-3'
+
+isValidSlug('valid-slug')  // true
+isValidSlug('Invalid Slug') // false
+```
+
+---
+
+### 8. Offline/PWA Module
+
+The offline module provides comprehensive PWA support with multi-tier storage.
+
+#### Storage Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Storage Manager                           │
+│  (Abstraction layer - auto-selects storage by size)         │
+└─────────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               │               ▼
+┌─────────────────────┐       │     ┌─────────────────────┐
+│    Cache API        │       │     │    IndexedDB        │
+│    (< 5MB files)    │       │     │    (≥ 5MB files)    │
+│                     │       │     │                     │
+│ • Fast access       │       │     │ • Large file support│
+│ • Service worker    │       │     │ • Video blobs       │
+│ • HTTP semantics    │       │     │ • Resume capability │
+└─────────────────────┘       │     └─────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────────┐
+                    │   Download Manager   │
+                    │                     │
+                    │ • Priority queue    │
+                    │ • Retry logic       │
+                    │ • Progress tracking │
+                    │ • Pause/resume      │
+                    └─────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────────┐
+                    │  Download EventBus  │
+                    │                     │
+                    │ • preloadStart      │
+                    │ • preloadProgress   │
+                    │ • preloadComplete   │
+                    │ • preloadError      │
+                    │ • queueUpdate       │
+                    └─────────────────────┘
+```
+
+---
+
+#### offline/StorageManager.ts
+**Purpose:** Abstraction layer for storing assets in Cache API or IndexedDB.
+
+**Key Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `getStorageQuota()` | Get storage quota information |
+| `requestPersistentStorage()` | Request persistent storage |
+| `shouldUseIndexedDB(size)` | Determine storage location |
+| `storeAsset(url, blob, metadata)` | Store asset (auto-selects storage) |
+| `getAsset(url)` | Retrieve asset from any storage |
+| `hasAsset(url)` | Check if asset exists |
+| `deleteAsset(url, assetId)` | Delete from all locations |
+| `clearAll()` | Clear all offline storage |
+
+**Storage Decision:**
+```typescript
+// Automatic storage selection based on file size
+static shouldUseIndexedDB(sizeBytes: number): boolean {
+  return sizeBytes >= OFFLINE_CONFIG.storage.indexedDbMinSize; // 5MB
+}
+```
+
+---
+
+#### offline/DownloadManager.ts
+**Purpose:** Manages asset downloads with queue, retry, and progress tracking.
+
+**Key Features:**
+- Priority-based download queue
+- Concurrent download limit
+- Automatic retry with exponential backoff
+- Progress tracking per download
+- Pause/resume support
+- Queue persistence for resume after reload
+
+**Key Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `addJob(params)` | Add download to queue |
+| `pauseAll()` | Pause all downloads |
+| `resumeAll()` | Resume downloads |
+| `cancelJob(jobId)` | Cancel specific download |
+| `cancelProjectDownloads(projectId)` | Cancel project downloads |
+| `clearQueue()` | Clear entire queue |
+| `getStatus()` | Get queue status |
+| `restoreQueue()` | Restore from IndexedDB |
+
+**Priority Calculation:**
+```typescript
+// Priority = assetType priority + variant priority
+// Higher priority downloads first
+private calculatePriority(assetType: AssetType, variantType: AssetVariantType): number {
+  const typePriority = PRELOAD_CONFIG.priority.assetType[assetType] || 0;
+  const variantPriority = PRELOAD_CONFIG.priority.variant[variantType] || 0;
+  return typePriority + variantPriority;
+}
+```
+
+---
+
+#### offline/DownloadEventBus.ts
+**Purpose:** Browser-native EventEmitter for asset preload progress tracking.
+
+**Event Types:**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `preloadStart` | `{ jobId, assetId, url }` | Download started |
+| `preloadProgress` | `{ jobId, progress, bytesLoaded, totalBytes }` | Progress update |
+| `preloadComplete` | `{ jobId, assetId }` | Download completed |
+| `preloadError` | `{ jobId, assetId, error }` | Download failed |
+| `queueUpdate` | void | Queue state changed |
+| `projectDownloadProgress` | `{ projectId, progress }` | Project progress |
+| `projectDownloadComplete` | `{ projectId }` | Project complete |
+
+**Usage:**
+```typescript
+import { downloadEventBus } from '@/lib/offline/DownloadEventBus';
+
+// Subscribe to progress
+const unsubscribe = downloadEventBus.on('preloadProgress', (data) => {
+  console.log(`${data.progress}% - ${data.bytesLoaded}/${data.totalBytes}`);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+---
+
+#### offlineDb/schema.ts
+**Purpose:** IndexedDB schema definition using Dexie.js.
+
+**Tables:**
+
+```typescript
+class OfflineDatabase extends Dexie {
+  assets!: EntityTable<OfflineAsset, 'id'>;
+  projects!: EntityTable<OfflineProject, 'id'>;
+  downloadQueue!: EntityTable<DownloadQueueItem, 'id'>;
+
+  constructor() {
+    super(OFFLINE_CONFIG.dbName);
+
+    this.version(OFFLINE_CONFIG.dbVersion).stores({
+      // Large files (videos > 5MB)
+      assets: 'id, projectId, url, variantType, assetType, downloadedAt',
+
+      // Project offline status
+      projects: 'id, slug, status, lastSyncedAt',
+
+      // Download queue (for resume)
+      downloadQueue: 'id, projectId, status, priority, addedAt',
+    });
+  }
+}
+```
+
+---
+
+#### offlineDb/OfflineDbManager.ts
+**Purpose:** CRUD operations for IndexedDB offline storage.
+
+**Asset Operations:**
+
+| Method | Description |
+|--------|-------------|
+| `storeAsset(asset)` | Store asset blob |
+| `getAsset(id)` | Get by ID |
+| `getAssetByUrl(url)` | Get by URL |
+| `getProjectAssets(projectId)` | Get all project assets |
+| `deleteAsset(id)` | Delete asset |
+| `deleteProjectAssets(projectId)` | Delete project assets |
+| `getTotalAssetsSize()` | Get total storage used |
+
+**Project Operations:**
+
+| Method | Description |
+|--------|-------------|
+| `upsertProject(project)` | Store/update project metadata |
+| `getProject(id)` | Get by ID |
+| `getProjectBySlug(slug)` | Get by slug |
+| `getAllProjects()` | Get all offline projects |
+| `updateProjectStatus(id, status)` | Update status |
+| `deleteProject(id)` | Delete project and assets |
+
+**Queue Operations:**
+
+| Method | Description |
+|--------|-------------|
+| `addToQueue(item)` | Add download item |
+| `getPendingQueue()` | Get pending items |
+| `updateQueueStatus(id, status)` | Update status |
+| `updateQueueProgress(id, bytes, total)` | Update progress |
+| `removeFromQueue(id)` | Remove item |
+| `resetFailedItems(projectId?)` | Reset failed to queued |
+
+---
+
+## Integration Patterns
+
+### 1. Asset URL Resolution Flow
+
+```
+User requests asset
+       │
+       ▼
+resolveAssetPlaybackUrl()
+       │
+       ├── data:/blob: URLs → Pass through
+       │
+       ├── /api/file/download → Pass through
+       │
+       ├── http(s):// URLs → Pass through
+       │
+       └── Relative paths
+              │
+              ├── Check presigned cache
+              │      │
+              │      ├── Found → Return presigned URL
+              │      │
+              │      └── Not found
+              │             │
+              │             └── Return proxy URL
+              │                 /api/file/download?privateUrl=...
+              │
+              └── Batch presigning available
+                     │
+                     └── queuePresignedUrls()
+                            │
+                            └── Fetch batch from server
+                                   POST /api/file/presign
+```
+
+### 2. Element Creation Flow
+
+```
+User adds element
+       │
+       ▼
+createDefaultElement(type)
+       │
+       ├── Generate ID
+       ├── Set position
+       ├── Apply TYPE_SPECIFIC_DEFAULTS
+       │
+       ▼
+mergeElementWithDefaults(element, projectDefaults)
+       │
+       ├── Apply style properties from defaults
+       ├── Normalize position/timing
+       ├── Handle arrays (galleryCards, carouselSlides)
+       │
+       ▼
+Element ready for use
+```
+
+### 3. Offline Download Flow
+
+```
+User initiates download
+       │
+       ▼
+downloadManager.addJob()
+       │
+       ├── Check if already cached → Skip
+       ├── Check if in queue → Skip
+       │
+       ▼
+Add to priority queue
+       │
+       ▼
+processQueue()
+       │
+       ├── Start download (fetch with streaming)
+       │      │
+       │      ├── Emit preloadStart
+       │      │
+       │      ├── Stream chunks
+       │      │      │
+       │      │      ├── Update bytesLoaded
+       │      │      ├── Emit preloadProgress
+       │      │      └── Persist progress to IndexedDB
+       │      │
+       │      └── Complete
+       │             │
+       │             ▼
+       │      StorageManager.storeAsset()
+       │             │
+       │             ├── Size < 5MB → Cache API
+       │             └── Size ≥ 5MB → IndexedDB
+       │
+       ├── Emit preloadComplete
+       │
+       └── On error
+              │
+              ├── Retry (up to maxRetries)
+              │
+              └── Emit preloadError
+```
+
+---
+
+## Configuration Dependencies
+
+The lib module uses configuration from:
+
+| Config File | Purpose |
+|-------------|---------|
+| `config/preload.config.ts` | Preload priorities, asset fields, storage limits |
+| `config/offline.config.ts` | Cache names, DB name/version, event names |
+| `config/index.ts` | Base API URL |
+
+---
+
+## Best Practices
+
+### 1. Always Use Type Guards
+```typescript
+// Prefer type guards over string comparison
+if (isNavigationElementType(element.type)) {
+  // TypeScript knows type is 'navigation_next' | 'navigation_prev'
+}
+```
+
+### 2. Use Presigned URLs When Available
+```typescript
+// Check presigned cache first for performance
+const url = getPresignedUrl(storageKey);
+if (url) {
+  // Direct S3 access - faster
+} else {
+  // Fall back to proxy
+}
+```
+
+### 3. Pre-decode Images Before Transitions
+```typescript
+// Always wait for images before page switch
+await waitForPageImages(targetPage, 2000, cacheProvider);
+setActivePage(targetPage);
+```
+
+### 4. Handle Offline Storage Appropriately
+```typescript
+// Let StorageManager decide storage location
+await StorageManager.storeAsset(url, blob, metadata);
+// Small files → Cache API
+// Large files → IndexedDB
+```
+
+---
+
+## Related Documentation
+
+- [hooks-module.md](./hooks-module.md) - Custom hooks using lib utilities
+- [stores-module.md](./stores-module.md) - Redux state management
+- [components-module.md](./components-module.md) - Components using lib utilities
+- [offline-pwa-mode.md](../../documentation/offline-pwa-mode.md) - PWA offline architecture
+- [assets-preloading.md](../../documentation/assets-preloading.md) - Asset preloading strategy
diff --git a/frontend/docs/navigation-smooth-transitions.md b/frontend/docs/navigation-smooth-transitions.md
new file mode 100644
index 0000000..db5b150
--- /dev/null
+++ b/frontend/docs/navigation-smooth-transitions.md
@@ -0,0 +1,854 @@
+# Navigation & Smooth Transitions Analysis
+
+## Executive Summary
+
+Deep analysis of how navigation works in the Tour Builder Platform - from Constructor editing to Runtime Presentations, across Online and Offline modes. This document traces each navigation thread step-by-step to verify that smooth transitions are robust.
+
+**Architecture Update:** The page navigation system was refactored from 6+ fragmented hooks into a unified state machine (`usePageNavigationState`). This consolidation:
+- Prevents race conditions via atomic `useReducer` transitions
+- Uses explicit phases instead of boolean flag combinations
+- Computes derived state (`isLoading`, `showSpinner`, etc.) from a single phase value
+- Provides a `PageNavigationContext` for child component access
+
+---
+
+## 1. NAVIGATION SYSTEM ARCHITECTURE
+
+### 1.1 Core Hooks (Shared Between Constructor & RuntimePresentation)
+
+| Hook | File | Purpose |
+|------|------|---------|
+| `usePageNavigation` | `hooks/usePageNavigation.ts` | Page navigation state with history tracking, browser-like back behavior |
+| `usePageNavigationState` | `hooks/usePageNavigationState.ts` | **Unified state machine** - URL resolution, switching, fade effects, cleanup (replaces 6 hooks) |
+| `useTransitionPlayback` | `hooks/useTransitionPlayback.ts` | Transition video playback, last frame preservation, pre-generated reverse support |
+| `usePreloadOrchestrator` | `hooks/usePreloadOrchestrator.ts` | Asset preloading with blob URL cache |
+| `useNetworkAware` | `hooks/useNetworkAware.ts` | Network condition monitoring |
+
+**Architecture Refactor Note:** The following hooks were consolidated into `usePageNavigationState`:
+- `usePageSwitch` - Page switching with blob URL resolution
+- `useBackgroundState` - Background ready tracking
+- `useBackgroundTransition` - CSS animation-based crossfade
+- `useTransitionCleanup` - Video cleanup coordination
+- `useBackgroundUrls` - URL resolution for display
+- `pageLoadingUtils` - Loading state computation
+
+### 1.2 Component Integration
+
+```
+RuntimePresentation.tsx / constructor.tsx
+    |
++----------------------------------------------------------------+
+|  usePageNavigation                                              |
+|  - Unified page history management (MAX_HISTORY_LENGTH = 50)    |
+|  - Browser-like back: history pops when isBack=true             |
+|  - Provides getNavigationContext() for resolveNavigationTarget()|
+|  - applyPageSelection(targetPageId, isBack) handles history     |
++----------------------------------------------------------------+
+    |
++----------------------------------------------------------------+
+|  usePreloadOrchestrator                                         |
+|  - Preloads assets for current + neighbor pages                 |
+|  - Provides getReadyBlobUrl() for O(1) instant lookup           |
+|  - Provides getCachedBlobUrl() for Cache API lookup             |
++----------------------------------------------------------------+
+    |
++----------------------------------------------------------------+
+|  usePageNavigationState (UNIFIED STATE MACHINE)                 |
+|  - navigateToPage() initiates navigation with URL resolution    |
+|  - Tracks phase: idle → preparing → transitioning/loading_bg    |
+|                → transition_done → fading_in → idle             |
+|  - Maintains currentImageUrl, previousImageUrl for overlay      |
+|  - Provides derived state: isLoading, showSpinner, showElements |
+|  - onBackgroundReady() callback for CanvasBackground            |
+|  - onTransitionEnded() callback for video transition completion |
+|  - Atomic state via useReducer (prevents race conditions)       |
++----------------------------------------------------------------+
+    |
++----------------------------------------------------------------+
+|  useTransitionPlayback                                          |
+|  - Plays transition videos with presigned URL fallback          |
+|  - Preserves last frame until onComplete callback               |
+|  - Uses pre-generated reversed videos for back navigation       |
+|  - Passes isBack to onComplete for proper history management    |
++----------------------------------------------------------------+
+```
+
+**Note:** `usePageNavigationState` consolidated 6 hooks into a single state machine:
+- URL resolution, switching, overlay management (from `usePageSwitch`)
+- Background ready tracking (from `useBackgroundState`)
+- Fade-out coordination (from `useBackgroundTransition`)
+- Video cleanup (from `useTransitionCleanup`)
+- URL resolution for display (from `useBackgroundUrls`)
+- Loading state computation (from `pageLoadingUtils`)
+
+---
+
+## 2. NAVIGATION WITHOUT TRANSITION VIDEO
+
+### 2.1 Flow Overview
+
+```
+User clicks navigation element (no transitionVideoUrl)
+    |
+handleElementClick / navigateToPage
+    |
+Direct navigation - no transition video
+```
+
+### 2.2 Step-by-Step Thread Analysis
+
+**Thread 1: Navigation Trigger**
+```
+handleElementClick(element)                    [RuntimePresentation:309-340]
+    |
+resolveNavigationTarget(element, pages)        [lib/navigationHelpers.ts]
+    +-- Extract targetPageSlug from element
+    +-- Find target page in pages array
+    +-- Return { pageId, transitionVideoUrl, isBack }
+    |
+navigateToPage(targetPageId, undefined, false) [No transition video]
+```
+
+**Thread 2: Page Switch Initiation**
+```
+navigateToPage(targetPageId, undefined, isBack) [RuntimePresentation:285-315]
+    |
+No transitionVideoUrl -> Direct navigation path
+    |
+setIsBackgroundReady(false)                    [Mark: waiting for new bg]
+lastInitializedPageIdRef.current = targetPageId
+    |
+await pageSwitch.switchToPage(targetPage, () => {
+    applyPageSelection(targetPageId, isBack);  [usePageNavigation hook]
+    // - If isBack=true AND target matches previous: history pops
+    // - Otherwise: history appends (trimmed to MAX_HISTORY_LENGTH=50)
+});
+```
+
+**Thread 3: URL Resolution & Overlay Setup**
+```
+switchToPage(targetPage, onSwitched)           [usePageSwitch:372-419]
+    |
+Save current as previous for overlay:
+    setPreviousBgImageUrl(currentBgImageUrlRef.current)
+    |
+setIsSwitching(true)
+setIsNewBgReady(false)
+    |
+Resolve URLs in parallel (prefer preloaded blob URLs):
+    [imageUrl, videoUrl, audioUrl] = await Promise.all([
+        resolveToDisplayUrl(background_image_url),
+        resolveMediaUrl(background_video_url),
+        resolveMediaUrl(background_audio_url),
+    ])
+```
+
+**Thread 4: Blob URL Resolution Priority**
+```
+resolveToDisplayUrl(storagePath)               [usePageSwitch:237-306]
+    |
+1. getReadyBlobUrl(storagePath)                [O(1) Map lookup - same session]
+       -> If found: return immediately (instant)
+    |
+2. getCachedBlobUrl(storagePath)               [Cache API lookup ~5ms]
+       -> If found: create blob URL, return
+    |
+3. resolveAssetPlaybackUrl(storagePath)        [Resolve to playback URL]
+       |
+4. getReadyBlobUrl(resolvedUrl)                [Fallback lookup]
+       -> If found: return
+    |
+5. getCachedBlobUrl(resolvedUrl)               [Fallback Cache API]
+       -> If found: return
+    |
+6. loadImageWithFallback(originalUrl, storageKey)  [Network fetch]
+       +-- Try presigned URL
+       +-- On CORS failure: markPresignedUrlFailed()
+       +-- Retry with proxy URL: /api/file/download
+```
+
+**Thread 5: Background Display & Overlay**
+```
+After URL resolution:
+    setCurrentBgImageUrl(imageUrl)
+    setCurrentBgVideoUrl(videoUrl)
+    setCurrentBgAudioUrl(audioUrl)
+    onSwitched()                               [Notify caller]
+    |
+For blob URLs (local data):
+    requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+            setIsNewBgReady(true)              [Mark ready after 2 frames]
+        })
+    })
+    |
+For remote images:
+    Wait for Image onLoad callback
+    -> markBackgroundReady()
+```
+
+**Thread 6: Render - Previous Background Overlay**
+```
+RuntimePresentation render                      [lines 517-528]
+    |
+{pageSwitch.previousBgImageUrl &&
+ pageSwitch.isSwitching &&
+ !pageSwitch.isNewBgReady && (
+    <div className="absolute inset-0 z-10"
+         style={{ backgroundImage: `url("${previousBgImageUrl}")` }}
+    />
+)}
+    |
+Previous page background stays visible until new one is ready!
+```
+
+**Thread 7: Overlay Clearing**
+```
+useBackgroundTransition effect                  [lines 144-158]
+    |
+When: isSwitching && isNewBgReady && previousBgImageUrl
+    |
+pageSwitch.clearPreviousBackground()
+    +-- setPreviousBgImageUrl('')
+    +-- setIsSwitching(false)
+    +-- revokeBlobUrl(prevUrl)                 [Memory cleanup]
+```
+
+### 2.3 Summary: Navigation WITHOUT Transition Video
+
+| Phase | What's Visible | State |
+|-------|----------------|-------|
+| 1. Click | Current page | `isSwitching: false` |
+| 2. Switch starts | Previous bg (z-0) fading out, New content (z-1) fading in | `isSwitching: true, isFadingIn: true` |
+| 3. Crossfade | Both visible with CSS animation | `animate-crossfade-out` / `animate-crossfade-in` |
+| 4. Animation ends | New page fully visible | `onAnimationEnd` fires, `isFadingIn: false` |
+| 5. Cleanup | New page only | `clearPreviousBackground()` called |
+
+### 2.4 CSS Animation-Based Crossfade
+
+The crossfade effect uses CSS animations instead of JS-controlled transitions:
+
+**CSS Variables (main.css) - Single Source of Truth:**
+```css
+:root {
+  --crossfade-duration: 700ms;
+  --crossfade-easing: cubic-bezier(0.4, 0, 0.2, 1);
+}
+```
+
+**CSS Classes (main.css):**
+```css
+.animate-crossfade-in {
+  animation: page-crossfade-in var(--crossfade-duration, 700ms) var(--crossfade-easing) forwards;
+}
+
+.animate-crossfade-out {
+  animation: page-crossfade-out var(--crossfade-duration, 700ms) var(--crossfade-easing) forwards;
+}
+```
+
+**Easing Characteristics:**
+- `cubic-bezier(0.4, 0, 0.2, 1)` - Material Design standard
+- Slow start prevents abrupt appearance
+- Smooth acceleration and soft landing
+
+**Why CSS Animations (not transitions):**
+- CSS animations always play when the class is added
+- Immune to React's render batching that can skip transition states
+- `onAnimationEnd` event provides reliable completion detection
+- Duration controlled via CSS variable (single source of truth)
+- JS can read duration via `getCrossfadeDuration()` utility
+
+**Hook Usage:**
+```typescript
+const { isFadingIn, onFadeInAnimationEnd } = useBackgroundTransition({
+  pageSwitch,
+  fadeIn: { hasActiveTransition: false },
+});
+
+// In JSX:
+<div
+  className={`absolute inset-0 z-1 ${isFadingIn ? 'animate-crossfade-in' : ''}`}
+  onAnimationEnd={onFadeInAnimationEnd}
+>
+  {/* New page content */}
+</div>
+
+// Previous background:
+{previousBgImageUrl && isFadingIn && (
+  <div className={`absolute inset-0 z-0 ${isFadingIn ? 'animate-crossfade-out' : ''}`}>
+    ...
+  </div>
+)}
+```
+
+**ROBUSTNESS CHECK: Previous page renders while next page background and UI elements not ready**
+
+---
+
+## 3. NAVIGATION WITH TRANSITION VIDEO
+
+### 3.1 Flow Overview
+
+```
+User clicks navigation element (has transitionVideoUrl)
+    |
+handleElementClick / navigateToPage
+    |
+Start transition video -> Play -> Keep last frame -> Switch page -> Fade out
+```
+
+### 3.2 Step-by-Step Thread Analysis
+
+**Thread 1: Transition Initiation**
+```
+navigateToPage(targetPageId, transitionVideoUrl, isBack)  [RuntimePresentation:272-307]
+    |
+Has transitionVideoUrl -> Transition path
+    |
+resetFadeOut()                                 [Clear previous fade state]
+setPendingTransitionComplete(false)
+    |
+setTransitionPreview({
+    targetPageId,
+    videoUrl: resolveAssetPlaybackUrl(transitionVideoUrl),
+    storageKey: transitionVideoUrl,            [Raw path for cache lookup]
+    isReverse: isBack,
+})
+```
+
+**Thread 2: Transition Video Source Resolution**
+```
+useTransitionPlayback effect triggers          [lines 355-771]
+    |
+resolvePlayableSource()                        [lines 431-540]
+    |
+1. getReadyBlobUrl(storageKey)                 [O(1) lookup by storage path]
+       -> If found: use cached blob URL
+    |
+2. getCachedBlobUrl(storageKey)                [Cache API by storage path]
+       -> If found: create blob URL, cache it
+    |
+3. Check lastLoadedBlobUrlRef (reuse same session)
+    |
+4. getReadyBlobUrl(sourceUrl)                  [Lookup by resolved URL]
+    |
+5. getCachedBlobUrl(sourceUrl)                 [Cache API by resolved URL]
+    |
+6. Network fetch as blob                       [Fallback - full download]
+       -> axios.get(requestUrl, { responseType: 'blob' })
+       -> URL.createObjectURL(blob)
+```
+
+**Thread 3: Video Playback**
+```
+loadAndPlay()                                  [lines 542-598]
+    |
+video.src = playableSourceUrl
+video.currentTime = 0
+video.load()
+attemptPlay()
+    |
+onPlaying event fires                          [lines 633-675]
+    |
+setPhase('playing')
+    |
+scheduleFinishByDuration(durationSec)          [lines 405-421]
+    +-- finishBeforeEndMs = 50                 [Finish 50ms BEFORE end]
+    +-- finishMs = durationSec * 1000 - 50
+    +-- setTimeout(() => finishPlayback('duration-timer'), finishMs)
+```
+
+**Thread 4: Last Frame Preservation (CRITICAL)**
+```
+finishPlayback(reason)                         [lines 244-293]
+    |
+didFinishRef.current = true
+clearTimers()
+    |
+video.pause()
+    |
+*** LAST FRAME PRESERVATION ***
+if (video.duration && Number.isFinite(video.duration) &&
+    video.currentTime >= video.duration - 0.1) {
+    video.currentTime = Math.max(0, video.duration - 0.05)
+}
+    |
+Explanation:
+- Some browsers show BLACK after 'ended' event
+- Seeking to duration - 0.05 keeps last visible frame
+- This ensures smooth visual continuity
+    |
+setPhase('finishing')
+    |
+Optional: waitForImages() for target page pre-decode
+    |
+setPhase('completed')
+onCompleteRef.current(targetPageId)
+```
+
+**Thread 5: Page Switch After Transition**
+```
+onComplete callback (targetPageId, isBack)     [RuntimePresentation:146-166]
+    |
+if (targetPageId) {
+    const targetPage = pages.find(p => p.id === targetPageId)
+    lastInitializedPageIdRef.current = targetPageId
+    |
+    await pageSwitch.switchToPage(targetPage, () => {
+        applyPageSelection(targetPageId, isBack ?? false)  [usePageNavigation]
+        // Proper history management: pops on back, appends on forward
+    })
+    |
+    setIsBackgroundReady(false)
+    setPendingTransitionComplete(true)         [Signal: waiting for bg ready]
+}
+```
+
+**Thread 6: Background Image Load Detection**
+```
+Background image element in render             [lines 476-514]
+    |
+<img onLoad={() => {
+    setIsBackgroundReady(true)
+    pageSwitch.markBackgroundReady()
+}} />
+    |
+Or for video backgrounds:
+useEffect auto-marks ready when no image or has video
+```
+
+**Thread 7: Video Transition Overlay Removal (Instant, With rAF Delay)**
+```
+TransitionPreviewOverlay.tsx
+    |
+When: isFadingOut=true passed from parent
+    |
+useEffect triggers:
+    if (isFadingOut) {
+        requestAnimationFrame(() => {
+            setShouldHide(true)   [After one paint frame]
+        })
+    }
+    |
+Container opacity:
+    - 0 during initial buffering (before first frame)
+    - 0 when shouldHide=true (after rAF delay - bg is painted)
+    - 1 otherwise (video playing)
+    |
+transition: 'none' when hiding [NO CSS transition - instant hide]
+```
+
+**Thread 8: Render - Transition Overlay Visibility**
+```
+TransitionPreviewOverlay component             [TransitionPreviewOverlay.tsx]
+    |
+Container opacity controlled by:
+    - isBuffering && !isVideoReady → 0 (initial buffering)
+    - shouldHide → 0 (after rAF delay, new bg painted)
+    - otherwise → opacity prop or 1
+    |
+transition: useTransition ? '150ms' : 'none'
+    - 150ms ONLY for initial buffering fade-in
+    - 'none' when hiding (instant hide since last video frame = new bg)
+    |
+{transitionPreview && (
+    <TransitionPreviewOverlay
+        isBuffering={transitionPhase === 'preparing' || isBuffering}
+        isFadingOut={pendingTransitionComplete && isBackgroundReady}
+    />
+)}
+    |
+Container hidden while: preparing, buffering  (old page visible through)
+Container visible when: video ready to play   (instant appearance)
+Overlay removed: instantly after rAF (ensures bg is painted first)
+```
+
+**Key Design Decision - Instant Hide with rAF Delay:**
+- Video itself IS the transition effect
+- First frame = old page background
+- Last frame = new page background
+- Wait one `requestAnimationFrame` after `isFadingOut=true`
+- This ensures new background is painted before hiding overlay
+- Overlay hides **instantly** (no CSS transition) - seamless since last frame = new bg
+- No visual discontinuity or flash
+
+### 3.3 Summary: Navigation WITH Transition Video
+
+| Phase | What's Visible | State |
+|-------|----------------|-------|
+| 1. Click | Current page | `transitionPhase: 'idle'` |
+| 2. Preparing | Current page (container hidden) | `transitionPhase: 'preparing', isBuffering: true` |
+| 3. Playing | Transition video | `transitionPhase: 'playing'` |
+| 4. Finishing | **Last frame of video** | `transitionPhase: 'finishing'` |
+| 5. Completed | **Last frame of video** | `pendingTransitionComplete: true` |
+| 6. Bg loading | **Last frame of video** (z-50) | New bg loading underneath |
+| 7. Bg ready | **Instant switch** | `setTransitionPreview(null)` (no fade!) |
+| 8. Done | New page only | Overlay removed |
+
+**Key Changes from Previous Implementation:**
+- Container hidden during buffering (no black flash)
+- No fade-out animation for video transitions
+- Instant overlay removal when background ready
+- Video itself is the transition (first frame = old, last frame = new)
+
+**ROBUSTNESS CHECK: Last video frame renders while next page background and UI elements not ready**
+
+### 3.4 PreviousBackgroundOverlay (Simplified)
+
+The `PreviousBackgroundOverlay` component was simplified to remove all fade logic:
+
+```tsx
+// PreviousBackgroundOverlay.tsx - Simplified implementation
+const PreviousBackgroundOverlay = ({
+  imageUrl,
+  isSwitching = false,
+  isNewBgReady = false,
+  className = '',
+}) => {
+  // Simple render logic: show while switching AND new bg not ready
+  const shouldRender = isSwitching && !isNewBgReady && !!imageUrl;
+
+  if (!shouldRender) return null;
+
+  return (
+    <div
+      className={`pointer-events-none absolute inset-0 z-2 ${className}`}
+      style={{
+        backgroundImage: `url("${imageUrl}")`,
+        backgroundSize: 'contain',
+        backgroundPosition: 'center',
+        backgroundRepeat: 'no-repeat',
+      }}
+    />
+  );
+};
+```
+
+**Changes from previous implementation:**
+- Removed all CSS transition/fade logic
+- Removed timeout fallbacks
+- Removed transition event handlers
+- Simplified to pure show/hide based on props
+- Hides **instantly** when `isNewBgReady=true`
+
+### 3.5 scheduleAfterPaint Helper
+
+The `CanvasBackground.tsx` uses a `scheduleAfterPaint` helper for video first-frame detection:
+
+```typescript
+/**
+ * Schedule a callback to run after the next browser paint.
+ * Uses double rAF pattern: first rAF schedules for next frame,
+ * second rAF ensures the frame has actually been committed.
+ */
+const scheduleAfterPaint = (callback: () => void): void => {
+  requestAnimationFrame(() => {
+    requestAnimationFrame(callback);
+  });
+};
+```
+
+**Usage in video first-frame detection:**
+```typescript
+// Using requestVideoFrameCallback for accurate first-frame detection
+if ('requestVideoFrameCallback' in video) {
+  video.requestVideoFrameCallback(() => {
+    clearTimeout(timeout);
+    scheduleAfterPaint(() => {
+      reportVideoReady();  // Called after frame is painted
+    });
+  });
+}
+```
+
+---
+
+## 4. ONLINE VS OFFLINE MODE
+
+### 4.1 Network Awareness
+
+```
+useNetworkAware hook                           [hooks/useNetworkAware.ts]
+    |
+Monitors:
+    - navigator.onLine
+    - connection.effectiveType (slow-2g, 2g, 3g, 4g)
+    - connection.downlink (Mbps)
+    - connection.rtt (ms)
+    - connection.saveData (boolean)
+    |
+Returns:
+    - networkInfo.isOnline
+    - recommendedConcurrency (1-3 based on connection)
+    - shouldPreloadAggressively
+    - suggestOfflineMode
+```
+
+### 4.2 Preload Orchestrator - Online Mode
+
+```
+processQueue()                                 [usePreloadOrchestrator:355-485]
+    |
+Guard: if (!networkInfo.isOnline) return       [Skip if offline]
+    |
+While queue has items && activeDownloads < recommendedConcurrency:
+    +-- Check preloadedUrls.has(url) -> skip if already loaded
+    +-- Check StorageManager.hasAsset(url) -> skip if cached
+    |   +-- If cached: createReadyBlobUrl() from cache
+    |
+    preloadWithProgress(url, jobId, assetId)
+        +-- fetch(url) with streaming progress
+        +-- Store in Cache API
+        +-- createReadyBlobUrl()
+```
+
+### 4.3 Preload Orchestrator - Offline Mode
+
+```
+processQueue()                                 [usePreloadOrchestrator:355-485]
+    |
+Guard: if (!networkInfo.isOnline) return       [Don't process queue when offline]
+    |
+BUT: isUrlCached check still works!
+    +-- StorageManager.hasAsset(url)
+    |   +-- Check IndexedDB: OfflineDbManager.hasAssetByUrl(url)
+    |   +-- Check Cache API: caches.open().match(url)
+    |
+Assets already downloaded are still accessible!
+```
+
+### 4.4 Navigation Flow - Same for Both Modes
+
+The navigation flow is **identical** for online and offline modes:
+
+1. **URL Resolution** - `resolveToDisplayUrl()` / `resolvePlayableSource()`
+   - Tries `getReadyBlobUrl()` first (in-memory Map - O(1))
+   - Tries `getCachedBlobUrl()` second (Cache API + IndexedDB)
+   - Falls back to network only if not cached
+
+2. **Blob URL Priority** - Cache is always checked first
+   ```
+   Online:  blob URL (cache) > presigned URL > proxy URL
+   Offline: blob URL (cache) > FAIL if not cached
+   ```
+
+3. **Transition Video** - Same playback logic
+   - If cached: plays from blob URL (instant)
+   - If not cached: depends on network availability
+
+### 4.5 Offline Storage Hierarchy
+
+```
+Asset lookup order (StorageManager)
+    |
+1. IndexedDB (files >= 5MB)
+   +-- OfflineDbManager.getAssetByUrl(url)
+    |
+2. Cache API (files < 5MB)
+   +-- caches.open('tour-builder-assets-v1').match(url)
+    |
+3. Network (online only)
+   +-- fetch(presignedUrl || proxyUrl)
+```
+
+### 4.6 Summary: Online vs Offline Differences
+
+| Aspect | Online Mode | Offline Mode |
+|--------|-------------|--------------|
+| Preload queue | Active processing | Paused (no new downloads) |
+| Asset resolution | Cache -> Network | Cache only |
+| Transition video | Cache -> Network | Cache only |
+| Background image | Cache -> Network | Cache only |
+| Navigation flow | Same | Same |
+| Overlay behavior | Same | Same |
+| Last frame handling | Same | Same |
+
+**ROBUSTNESS CHECK: Same navigation flow works in both online and offline modes**
+
+---
+
+## 5. CONSTRUCTOR VS RUNTIME PRESENTATION
+
+### 5.1 Shared Components
+
+Both use the **same hooks**:
+- `usePageNavigationState` - Unified state machine for URL resolution, overlay management, fade effects
+- `useTransitionPlayback` - Video playback, last frame preservation
+- `usePreloadOrchestrator` - Asset preloading
+- `usePageNavigation` - History tracking
+
+### 5.2 Key Differences
+
+| Aspect | Constructor | RuntimePresentation |
+|--------|-------------|---------------------|
+| State management | `usePageNavigationState` (unified) | `usePageNavigationState` (unified) |
+| Crossfade animation | Yes (project transition settings) | Yes (project transition settings) |
+| Crossfade easing | From `transitionSettings.fadeEasing` | From `transitionSettings.fadeEasing` |
+| Transition video fade-out | **No (instant removal)** | **No (instant removal)** |
+| Video overlay hiding | Container hidden while buffering | Container hidden while buffering |
+| Background transition config | Via `usePageNavigationState` | Via `usePageNavigationState` |
+| Overlay component | `TransitionPreviewOverlay` | `TransitionPreviewOverlay` |
+| Post-transition cleanup | Via `onTransitionEnded` + `onBackgroundReady` | Via `onTransitionEnded` + `onBackgroundReady` |
+| Animation end detection | CSS `onAnimationEnd` event | CSS `onAnimationEnd` event |
+| Edit mode support | Direct background updates (`setBackgroundDirectly`) | N/A |
+
+### 5.3 Constructor Transition Flow
+
+```
+onComplete callback (targetPageId, isBack)     [constructor.tsx]
+    |
+if (targetPageId) {
+    await navState.navigateToPage(targetPage, {
+        hasTransition: false,
+        isBack: isBack ?? false,
+        onSwitched: () => applyPageSelection(targetPage.id, isBack ?? false)
+    })
+    // navigateToPage handles all state transitions atomically
+    // usePageNavigation handles history (pops on back, appends on forward)
+    clearSelection()
+    setSelectedMenuItem('none')
+}
+    |
+navState.onTransitionEnded() is called when transition video completes
+    |
+Video cleanup happens via effect watching pendingTransitionComplete + isBackgroundReady
+```
+
+Both constructor and runtime presentation use the same `usePageNavigationState` hook for unified state management. The `usePageNavigation` hook handles browser-like history behavior.
+
+---
+
+## 6. ROBUSTNESS VERIFICATION
+
+### 6.1 Scenario: Navigation WITHOUT Transition (Direct)
+
+| Step | What Happens | Verified |
+|------|--------------|----------|
+| 1 | User clicks navigation element | YES |
+| 2 | Previous bg saved to `previousBgImageUrl` | YES |
+| 3 | `isSwitching: true, isNewBgReady: false` | YES |
+| 4 | URL resolution (blob -> cache -> network) | YES |
+| 5 | Previous bg overlay renders (z-10) | YES |
+| 6 | New bg loads underneath (z-1) | YES |
+| 7 | Image onLoad -> `markBackgroundReady()` | YES |
+| 8 | `clearPreviousBackground()` removes overlay | YES |
+
+### 6.2 Scenario: Navigation WITH Transition Video
+
+| Step | What Happens | Verified |
+|------|--------------|----------|
+| 1 | User clicks navigation element | YES |
+| 2 | `setTransitionPreview()` triggers hook | YES |
+| 3 | Video source resolved (blob -> cache -> network) | YES |
+| 4 | Video plays (opacity: 1) | YES |
+| 5 | Timer fires 50ms before video ends | YES |
+| 6 | `finishPlayback()` seeks to duration - 0.05 | YES |
+| 7 | Last frame stays visible | YES |
+| 8 | `onComplete()` triggers page switch | YES |
+| 9 | New bg loads underneath overlay | YES |
+| 10 | Image onLoad -> `isBackgroundReady: true` | YES |
+| 11 | Overlay fades out (opacity: 0 transition) | YES |
+| 12 | Cleanup: remove video src, clear state | YES |
+
+### 6.3 Scenario: Reverse Navigation (Back)
+
+| Step | What Happens | Verified |
+|------|--------------|----------|
+| 1 | User clicks back navigation | YES |
+| 2 | `isBack: true` set, uses `reverseVideoUrl` | YES |
+| 3 | Pre-generated reversed video loaded | YES |
+| 4 | Forward playback of reversed video | YES |
+| 5 | Video ends normally | YES |
+| 6 | `onComplete()` -> `finishPlayback()` | YES |
+| 7 | Same cleanup flow as forward | YES |
+
+**Note:** Reversed videos are pre-generated server-side using FFmpeg when pages are saved. This eliminates client-side frame-stepping and ensures professional audio/video synchronization.
+
+### 6.4 Scenario: Offline Mode
+
+| Step | What Happens | Verified |
+|------|--------------|----------|
+| 1 | `networkInfo.isOnline: false` | YES |
+| 2 | Preload queue paused | YES |
+| 3 | Navigation clicked | YES |
+| 4 | URL resolved from cache (IndexedDB/Cache API) | YES |
+| 5 | If cached: works identically to online | YES |
+| 6 | If not cached: fails gracefully | YES |
+
+---
+
+## 7. CONCLUSION
+
+The navigation and smooth transitions system is **robust and comprehensive**:
+
+### 7.1 Key Strengths
+
+1. **Unified State Machine** - `usePageNavigationState` consolidates 6 hooks into atomic state transitions
+2. **Race Condition Prevention** - `useReducer` ensures state updates are atomic (no batching issues)
+3. **Explicit Phase Tracking** - Single `phase` value (idle, preparing, transitioning, etc.) instead of multiple boolean flags
+4. **Derived State via useMemo** - `isLoading`, `showSpinner`, `showElements` computed from phase
+5. **Unified History Management** - `usePageNavigation` hook handles history in both components
+6. **Browser-Like Back Navigation** - History pops when navigating back (via `applyPageSelection(id, isBack=true)`)
+7. **History Limit** - `MAX_HISTORY_LENGTH=50` prevents unbounded growth in long sessions
+8. **Blob URL Priority** - Always checks cache before network
+9. **CSS Animation Crossfade** - Uses CSS animations (not transitions) for reliable visual effects
+10. **Smooth Easing** - Project-configurable transition easing
+11. **Event-Based Completion** - `onAnimationEnd` event replaces timer-based duration tracking
+12. **Previous Background Overlay** - Keeps previous page visible during direct navigation
+13. **Last Frame Preservation** - Seeks to duration - 0.05 to avoid black frame
+14. **Timer-Based Finish** - Finishes 50ms before video ends to catch last frame
+15. **No Video Fade** - Video transitions end instantly without fade-out animation
+16. **Container Hidden While Buffering** - Prevents black flash before video ready
+17. **Offline Resilience** - Same flow works when offline (if assets cached)
+18. **Context Provider** - `PageNavigationContext` allows child components to access navigation state
+
+### 7.2 No Gaps Identified
+
+- **State consistency**: Single `useReducer` prevents race conditions from async batching
+- **Invalid states impossible**: State machine phases prevent flag combinations like `isLoading && showElements`
+- **Pages without transition**: Previous page renders while next loads (crossfade animation)
+- **Pages with transition**: Last frame renders while next loads (instant switch when ready)
+- **Video overlay**: Container hidden while buffering (no black flash)
+- **Online mode**: Full preloading and network fallback
+- **Offline mode**: Graceful cache-first behavior
+- **Constructor**: Same `usePageNavigationState` hook as RuntimePresentation
+- **Edit mode**: Direct background updates via `setBackgroundDirectly()` bypass navigation flow
+
+---
+
+## 8. CRITICAL CODE LOCATIONS
+
+| Feature | File | Lines |
+|---------|------|-------|
+| Page navigation with history | `usePageNavigation.ts` | 62-195 |
+| History limit (MAX=50) | `usePageNavigation.ts` | 8 |
+| Browser-like history pop | `usePageNavigation.ts` | 120-127 |
+| Navigation context | `usePageNavigation.ts` | 164-170 |
+| **Unified state machine** | `usePageNavigationState.ts` | Full file (~520 LOC) |
+| State machine reducer | `usePageNavigationState.ts` | 80-180 |
+| Navigation phases | `usePageNavigationState.ts` | 30-45 |
+| URL resolution | `usePageNavigationState.ts` | 200-280 |
+| Derived state (isLoading, etc.) | `usePageNavigationState.ts` | 350-400 |
+| onBackgroundReady callback | `usePageNavigationState.ts` | 420-450 |
+| Transition video playback | `useTransitionPlayback.ts` | 355-771 |
+| Last frame preservation | `useTransitionPlayback.ts` | 251-262 |
+| Timer-based finish | `useTransitionPlayback.ts` | 405-421 |
+| isBack in onComplete | `useTransitionPlayback.ts` | 290-296 |
+| CSS variables (duration, easing) | `css/main.css` | 15-20 |
+| CSS animations | `css/main.css` | 42-120 |
+| getCrossfadeDuration utility | `lib/browserUtils.ts` | 14-32 |
+| TransitionPreviewOverlay | `Constructor/TransitionPreviewOverlay.tsx` | 1-75 |
+| PageNavigationContext provider | `context/PageNavigationContext.tsx` | Full file (~120 LOC) |
+| Network awareness | `useNetworkAware.ts` | 68-163 |
+| Server-side reversal | `backend/src/services/videoProcessing.ts` | N/A |
+| Preload queue guard | `usePreloadOrchestrator.ts` | 355-358 |
+| Navigation helpers | `lib/navigationHelpers.ts` | 1-120 |
+
+**Deleted Files (consolidated into `usePageNavigationState.ts`):**
+- `usePageSwitch.ts` (~475 LOC)
+- `useBackgroundState.ts` (~156 LOC)
+- `useBackgroundTransition.ts` (~164 LOC)
+- `useTransitionCleanup.ts` (~108 LOC)
+- `useBackgroundUrls.ts` (~104 LOC)
+- `lib/pageLoadingUtils.ts` (~76 LOC)
diff --git a/frontend/docs/pages-module.md b/frontend/docs/pages-module.md
new file mode 100644
index 0000000..2dbe131
--- /dev/null
+++ b/frontend/docs/pages-module.md
@@ -0,0 +1,1153 @@
+# Frontend Pages Module
+
+## Overview
+
+The Pages module implements all Next.js pages using the **Pages Router** pattern. It contains 99 TypeScript files providing entry points for routing, authentication flows, entity CRUD operations, and specialized features like the visual tour builder and runtime presentations.
+
+**Location:** `frontend/src/pages/`
+
+**Total Files:** 100 TypeScript/TSX files
+
+**Router:** Next.js Pages Router (not App Router)
+
+**Rendering:** Client-Side Rendering (CSR) - appropriate for admin/builder applications
+
+---
+
+## Architecture Diagram
+
+```
+pages/
+│
+├── _app.tsx                    # App entry point (324 LOC)
+│   ├── Redux Provider
+│   ├── DownloadContext Provider
+│   ├── Axios interceptors
+│   ├── PWA service worker
+│   ├── ErrorBoundary
+│   └── IntroGuide tour system
+│
+├── index.tsx                   # Root redirect → /
+├── login.tsx                   # Auth → /login
+├── forgot.tsx                  # Auth → /forgot
+├── verify-email.tsx            # Auth → /verify-email
+├── password-reset.tsx          # Auth → /password-reset
+│
+├── dashboard.tsx               # Admin home → /dashboard
+├── profile.tsx                 # User profile → /profile
+├── search.tsx                  # Global search → /search
+├── error.tsx                   # Error page → /error
+│
+├── constructor.tsx             # Visual builder → /constructor (1515 LOC)
+├── element-type-defaults.tsx   # Global element defaults → /element-type-defaults
+├── global-transition-defaults.tsx # Global transitions → /global-transition-defaults
+├── global-ui-control-defaults.tsx # Global UI controls → /global-ui-control-defaults
+├── global-ui-control-defaults/[controlType].tsx # Single global UI control
+├── project-element-defaults.tsx# Project element defaults → /project-element-defaults
+├── project-ui-control-settings.tsx # Project UI controls → /project-ui-control-settings
+│
+├── privacy-policy.tsx          # Legal → /privacy-policy
+├── terms-of-use.tsx            # Legal → /terms-of-use
+│
+├── p/[projectSlug]/            # Public presentations
+│   ├── index.tsx               # Production → /p/[slug]
+│   └── stage.tsx               # Stage preview → /p/[slug]/stage
+│
+├── api/                        # API routes
+│   ├── logError.ts             # Error logging endpoint
+│   └── hello.js                # Health check
+│
+└── [entity]/                   # 13 entity CRUD directories
+    ├── [entity]-list.tsx       # List with filters
+    ├── [entity]-new.tsx        # Create form
+    ├── [entity]-edit.tsx       # Edit form
+    ├── [entity]-view.tsx       # Read-only view
+    ├── [entity]-table.tsx      # Embedded table
+    └── [entityId].tsx          # Dynamic route
+```
+
+---
+
+## Page Categories
+
+### 1. App Entry (`_app.tsx`)
+
+**Location:** `pages/_app.tsx`
+**Size:** 324 LOC
+
+The application entry point that wraps all pages with providers and global functionality.
+
+**Responsibilities:**
+
+| Feature | Description |
+|---------|-------------|
+| Redux Provider | Wraps app with Redux store |
+| DownloadContext | PWA download progress tracking |
+| Axios Setup | Base URL, JWT interceptors, 401 handling |
+| PWA Registration | Service worker registration (production only) |
+| ErrorBoundary | Global error catching |
+| IntroGuide | Optional tour guide system |
+| Head Meta | SEO, OG tags, PWA manifest |
+| DevModeBadge | Development mode indicator |
+
+**Key Code Patterns:**
+
+```typescript
+// Per-page layout pattern
+export type NextPageWithLayout<P = Record<string, unknown>, IP = P> = NextPage<P, IP> & {
+  getLayout?: (page: ReactElement) => ReactNode;
+};
+
+function MyApp({ Component, pageProps }: AppPropsWithLayout) {
+  const getLayout = Component.getLayout || ((page) => page);
+
+  return (
+    <Provider store={store}>
+      <DownloadProvider>
+        {getLayout(
+          <>
+            <Head>...</Head>
+            <ErrorBoundary>
+              <Component {...pageProps} />
+            </ErrorBoundary>
+            <IntroGuide ... />
+            {isDev && <DevModeBadge />}
+          </>
+        )}
+      </DownloadProvider>
+    </Provider>
+  );
+}
+```
+
+**Axios Interceptors:**
+
+```typescript
+// Request interceptor - attach JWT token
+axios.interceptors.request.use((config) => {
+  const token = sessionStorage.getItem('token') || localStorage.getItem('token');
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+
+// Response interceptor - handle 401, presigned URL failures
+axios.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    // Handle presigned S3 URL failures (CORS issues)
+    if (isPresignedS3Url(requestUrl) && isNetworkError) {
+      disablePresignedUrls();
+    }
+
+    // Handle 401 - clear tokens, redirect to login
+    if (status === 401 && !isLoginRequest) {
+      sessionStorage.removeItem('token');
+      localStorage.removeItem('token');
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+---
+
+### 2. Authentication Pages
+
+| Page | Route | Layout | Description |
+|------|-------|--------|-------------|
+| `login.tsx` | `/login` | Guest | Email/password login with OAuth hints |
+| `forgot.tsx` | `/forgot` | Guest | Password reset request |
+| `verify-email.tsx` | `/verify-email` | Guest | Email verification callback |
+| `password-reset.tsx` | `/password-reset` | Guest | Password reset with token |
+
+**Login Page Pattern:**
+
+```typescript
+export default function Login() {
+  const dispatch = useAppDispatch();
+  const { currentUser, isFetching, errorMessage, token } = useAppSelector(
+    (state) => state.auth
+  );
+
+  // Fetch user data when token exists
+  useEffect(() => {
+    if (token) dispatch(findMe());
+  }, [token]);
+
+  // Redirect to dashboard if logged in
+  useEffect(() => {
+    if (currentUser?.id) router.push('/dashboard');
+  }, [currentUser?.id]);
+
+  const handleSubmit = async (values) => {
+    await dispatch(loginUser(values));
+  };
+
+  return (
+    <SectionFullScreen bg='violet'>
+      <CardBox>
+        <Formik initialValues={...} onSubmit={handleSubmit}>
+          <Form>
+            <FormField label='Login'>
+              <Field name='email' />
+            </FormField>
+            <FormField label='Password'>
+              <Field name='password' type='password' />
+            </FormField>
+            <BaseButton type='submit' label={isFetching ? 'Loading...' : 'Login'} />
+          </Form>
+        </Formik>
+      </CardBox>
+    </SectionFullScreen>
+  );
+}
+
+Login.getLayout = (page: ReactElement) => <LayoutGuest>{page}</LayoutGuest>;
+```
+
+---
+
+### 3. Dashboard Page
+
+**Location:** `pages/dashboard.tsx`
+**Size:** 203 LOC
+**Route:** `/dashboard`
+
+Admin home page displaying entity counts and AI-generated widgets.
+
+**Features:**
+- Entity count cards with permission-based visibility
+- Links to entity list pages
+- Redirects viewer-only users with private production grants to the first
+  allowed private presentation
+
+**Key Implementation:**
+
+```typescript
+const Dashboard = () => {
+  const { currentUser } = useAppSelector((state) => state.auth);
+  const { getCount, getVisibleEntities } = useDashboardCounts(currentUser);
+
+  const visibleEntities = getVisibleEntities();
+
+  return (
+    <SectionMain>
+      <div className='grid grid-cols-1 lg:grid-cols-3 gap-6'>
+        {visibleEntities.map((entity) => (
+          <DashboardCard
+            key={entity.key}
+            href={entity.href}
+            label={entity.label}
+            count={getCount(entity.key)}
+            iconKey={entity.icon}
+          />
+        ))}
+      </div>
+    </SectionMain>
+  );
+};
+
+Dashboard.getLayout = (page) => <LayoutAuthenticated>{page}</LayoutAuthenticated>;
+```
+
+---
+
+### 4. Entity CRUD Pages (78 pages)
+
+Each of the 13 entities has 6 standardized pages following consistent patterns.
+
+**Entities:**
+- users, roles, permissions
+- projects, project_memberships
+- assets, asset_variants, presigned_url_requests
+- tour_pages, project_audio_tracks
+- publish_events, pwa_caches, access_logs
+
+#### 4.1 List Page (`[entity]-list.tsx`)
+
+**Pattern:** Uses `createListPage` factory for most entities.
+
+**Factory Usage:**
+
+```typescript
+// pages/users/users-list.tsx
+import { createListPage } from '../../factories/createListPage';
+import TableUsers from '../../components/Users/TableUsers';
+import { uploadCsv, setRefetch } from '../../stores/users/usersSlice';
+
+const filters = [
+  { label: 'First Name', title: 'firstName' },
+  { label: 'Last Name', title: 'lastName' },
+  { label: 'E-Mail', title: 'email' },
+];
+
+export default createListPage({
+  entityName: 'users',
+  entityTitle: 'Users',
+  TableComponent: TableUsers,
+  filters,
+  readPermission: 'READ_USERS',
+  createPermission: 'CREATE_USERS',
+  uploadCsvAction: uploadCsv,
+  setRefetchAction: setRefetch,
+  newItemLabel: 'Add/Invite User',
+});
+```
+
+**Generated Features:**
+- Title and breadcrumbs
+- "New Item" button (permission-checked)
+- Filter button (adds filter rows)
+- Download CSV button
+- Upload CSV button with modal
+- Entity-specific table component
+
+**Custom List Page Example (assets-list.tsx):**
+
+```typescript
+const AssetsTablesPage = () => {
+  const { selectedProjectId } = useProjectSelector({ currentUser });
+  const { uploadingSections, runBatchUpload } = useAssetUploader({
+    selectedProjectId,
+    onUploadComplete: () => loadAssets(selectedProjectId),
+  });
+
+  return (
+    <SectionMain>
+      <div className='grid grid-cols-1 xl:grid-cols-2 gap-4'>
+        {ASSET_SECTIONS.map((section) => (
+          <AssetSectionCard
+            key={section.key}
+            section={section}
+            assets={assetsBySection[section.key]}
+            onUpload={(files) => runBatchUpload(section, files)}
+            onDeleteAsset={handleDeleteAsset}
+          />
+        ))}
+      </div>
+    </SectionMain>
+  );
+};
+
+AssetsTablesPage.getLayout = (page) => (
+  <LayoutAuthenticated permission='READ_ASSETS'>{page}</LayoutAuthenticated>
+);
+```
+
+#### 4.2 New Page (`[entity]-new.tsx`)
+
+**Pattern:** Formik form with initial empty values.
+
+```typescript
+// pages/projects/projects-new.tsx
+const initialValues = {
+  name: '',
+  slug: '',
+  description: '',
+  // ... all entity fields
+};
+
+const ProjectsNew = () => {
+  const dispatch = useAppDispatch();
+  const router = useRouter();
+
+  const handleSubmit = async (data) => {
+    await dispatch(create(data));
+    await router.push('/projects/projects-list');
+  };
+
+  return (
+    <SectionMain>
+      <CardBox>
+        <Formik initialValues={initialValues} onSubmit={handleSubmit}>
+          <Form>
+            <FormField label='Name'>
+              <Field name='name' placeholder='Name' />
+            </FormField>
+            {/* More fields */}
+            <BaseButtons>
+              <BaseButton type='submit' label='Submit' />
+              <BaseButton type='reset' label='Reset' />
+              <BaseButton label='Cancel' onClick={() => router.push('...-list')} />
+            </BaseButtons>
+          </Form>
+        </Formik>
+      </CardBox>
+    </SectionMain>
+  );
+};
+
+ProjectsNew.getLayout = (page) => (
+  <LayoutAuthenticated permission='CREATE_PROJECTS'>{page}</LayoutAuthenticated>
+);
+```
+
+#### 4.3 Edit Page (`[entity]-edit.tsx`)
+
+**Pattern:** Uses `useEditPageSync` hook for data loading and form sync.
+
+```typescript
+// pages/assets/assets-edit.tsx
+const EditAssetsPage = () => {
+  const router = useRouter();
+  const dispatch = useAppDispatch();
+
+  const { values: initialValues, setValues, id } = useEditPageSync({
+    entitySelector: (state) => state.assets.assets,
+    fetchAction: fetch,
+    initialValues: initVals,
+  });
+
+  const handleSubmit = async (data) => {
+    if (id) {
+      await dispatch(update({ id, data }));
+      await router.push('/assets/assets-list');
+    }
+  };
+
+  return (
+    <Formik enableReinitialize initialValues={initialValues} onSubmit={handleSubmit}>
+      <Form>
+        {/* Form fields */}
+      </Form>
+    </Formik>
+  );
+};
+
+EditAssetsPage.getLayout = (page) => (
+  <LayoutAuthenticated permission='UPDATE_ASSETS'>{page}</LayoutAuthenticated>
+);
+```
+
+#### 4.4 View Page (`[entity]-view.tsx`)
+
+**Pattern:** Read-only display with related entity tables.
+
+```typescript
+// pages/projects/projects-view.tsx
+const ProjectsView = () => {
+  const dispatch = useAppDispatch();
+  const project = useAppSelector((state) => state.projects.projects);
+  const { id } = router.query;
+
+  useEffect(() => {
+    dispatch(fetch({ id }));
+  }, [id]);
+
+  return (
+    <SectionMain>
+      <CardBox>
+        {/* Main entity fields */}
+        <div className='mb-4'>
+          <p className='block font-bold mb-2'>Name</p>
+          <p>{project?.name}</p>
+        </div>
+
+        {/* Related entities tables */}
+        <p className='block font-bold mb-2'>Assets</p>
+        <CardBox hasTable>
+          <table>
+            <thead>...</thead>
+            <tbody>
+              {project?.assets_project?.map((item) => (
+                <tr key={item.id} onClick={() => router.push(`/assets/assets-view/?id=${item.id}`)}>
+                  <td>{item.name}</td>
+                  {/* More columns */}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </CardBox>
+      </CardBox>
+    </SectionMain>
+  );
+};
+
+ProjectsView.getLayout = (page) => (
+  <LayoutAuthenticated permission='READ_PROJECTS'>{page}</LayoutAuthenticated>
+);
+```
+
+#### 4.5 Table Page (`[entity]-table.tsx`)
+
+**Pattern:** Embedded table for use within other pages.
+
+```typescript
+// Minimal wrapper around the table component
+// Usually just renders the table with pagination
+```
+
+#### 4.6 Dynamic Route (`[entityId].tsx`)
+
+**Pattern:** Project workspace or redirect to view page.
+
+**Project Workspace Example:**
+
+```typescript
+// pages/projects/[projectsId].tsx
+const ProjectWorkspacePage = () => {
+  const { projectsId } = router.query;
+  const [project, setProject] = useState(null);
+
+  // Load project data
+  useEffect(() => {
+    if (!projectId) return;
+    axios.get(`/projects/${projectId}`).then((res) => setProject(res.data));
+  }, [projectId]);
+
+  return (
+    <SectionMain>
+      {/* Project info card */}
+      <CardBox>
+        <h2>{project?.name}</h2>
+        <p>Slug: {project?.slug}</p>
+      </CardBox>
+
+      {/* Action cards grid */}
+      <div className='grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4 gap-4'>
+        <CardBox>
+          <h3>Constructor</h3>
+          <BaseButton href={`/constructor?projectId=${projectId}`} label='Open Constructor' />
+        </CardBox>
+        <CardBox>
+          <h3>Assets</h3>
+          <BaseButton href={`/assets/assets-list?projectId=${projectId}`} label='Open Assets' />
+        </CardBox>
+        {/* More action cards */}
+      </div>
+
+      {/* Publish section */}
+      <CardBox>
+        <h3>Publish</h3>
+        <BaseButtons>
+          <BaseButton label='Publish to Production' onClick={() => setIsPublishModalActive(true)} />
+          <BaseButton label='To Production Presentation' onClick={() => window.open(presentationLinks.production)} />
+          <BaseButton label='To Stage Presentation' onClick={() => window.open(presentationLinks.stage)} />
+        </BaseButtons>
+      </CardBox>
+    </SectionMain>
+  );
+};
+```
+
+---
+
+### 5. Constructor Page
+
+**Location:** `pages/constructor.tsx`
+**Size:** 1515 LOC (largest page)
+**Route:** `/constructor?projectId=X`
+
+Visual tour builder with canvas-based element editing.
+
+**Features:**
+- Canvas with background image/video/audio
+- Draggable positioned elements
+- Element editor panel with General/CSS/Effects tabs
+- Main constructor toolbar with Edit/Interact mode, Page actions, Elements
+  actions, Save, Stage, Exit, and Collapse sections
+- Save and Stage toolbar buttons keep a fixed compact width and reserve the
+  timestamp row to avoid layout shifts between one-line and two-line states
+- Page selector, reorder, create, duplicate, and delete actions
+- Element copy/paste across pages in the same presentation
+- Transition preview
+- Asset preloading with blob URL caching
+- Gallery carousel overlay with draggable buttons
+
+**Key Hooks Used:**
+
+| Hook | Purpose |
+|------|---------|
+| `useConstructorElements` | Element CRUD, selection, nested item helpers, and constructor-local element clipboard |
+| `useConstructorPageActions` | Page save/create/duplicate and Save to Stage operations |
+| `useCanvasElementDrag` | Element positioning with percentage coordinates |
+| `useTransitionPreview` | Transition video preview state |
+| `usePreloadOrchestrator` | Asset preloading with S3 presigned URLs |
+| `usePageSwitch` | Page navigation with background transitions |
+| `useTransitionPlayback` | Transition video playback coordination |
+| `useBackgroundTransition` | Background overlay during page switch |
+| `useIconPreload` | Icon asset preloading |
+| `useMediaDurationProbe` | Media duration extraction with caching |
+| `useDraggable` | Draggable panel positioning |
+| `useOutsideClick` | Click-outside detection for deselection |
+
+**Component Structure:**
+
+```typescript
+const ConstructorPage = () => {
+  const router = useRouter();
+  const canvasRef = useRef<HTMLDivElement>(null);
+
+  const projectId = router.query.projectId;
+  const pageIdFromRoute = router.query.pageId;
+
+  // Element management
+  const {
+    elements,
+    getElements,
+    selectedElementId,
+    selectedElement,
+    addElement,
+    updateElement,
+    removeSelectedElement,
+    selectElement,
+    copySelectedElement,
+    pasteCopiedElement,
+    canPasteElement,
+  } = useConstructorElements({
+    initialElements,
+    elementDefaultsByType,
+    allowedNavigationTypes,
+  });
+
+  // Page persistence and page creation/duplication
+  const {
+    saveConstructor,
+    saveToStage,
+    createPage,
+    duplicatePage,
+  } = useConstructorPageActions({
+    activePageId,
+    elements,
+    getElements,
+    pageBackground,
+    onReload: handleReload,
+  });
+
+  return (
+    <div className='flex h-screen'>
+      <ConstructorToolbar
+        pages={pages}
+        activePageId={activePageId}
+        onPageChange={setActivePageId}
+        onAddElement={addElement}
+        onCopyElement={copySelectedElement}
+        onPasteElement={pasteCopiedElement}
+        canCopyElement={Boolean(selectedElement)}
+        canPasteElement={canPasteElement}
+        onSave={saveConstructor}
+        onSaveToStage={saveToStage}
+      />
+
+      {/* Center: Canvas */}
+      <div ref={canvasRef} className='flex-1 relative'>
+        <CanvasBackground page={currentPage} />
+        {elements.map((element) => (
+          <CanvasElementComponent
+            key={element.id}
+            element={element}
+            isSelected={element.id === selectedElementId}
+            onSelect={() => selectElement(element.id)}
+            onUpdate={updateElement}
+          />
+        ))}
+      </div>
+
+      {/* Right: Element Editor */}
+      {selectedElementId && (
+        <ElementEditorPanel
+          element={selectedElement}
+          onUpdate={updateElement}
+          onDelete={removeSelectedElement}
+        />
+      )}
+
+      {/* Overlays */}
+      <TransitionPreviewOverlay />
+    </div>
+  );
+};
+
+ConstructorPage.getLayout = (page) => (
+  <LayoutAuthenticated permission='UPDATE_TOUR_PAGES'>{page}</LayoutAuthenticated>
+);
+```
+
+---
+
+### 6. Runtime Presentation Pages
+
+Public presentation pages for viewing published tours.
+
+#### Production Presentation
+
+**Location:** `pages/p/[projectSlug]/index.tsx`
+**Route:** `/p/[slug]` (e.g., `/p/cardiff`)
+
+```typescript
+export default function ProductionPresentation() {
+  const router = useRouter();
+  const { projectSlug } = router.query;
+
+  if (!projectSlug || typeof projectSlug !== 'string') {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <RuntimePresentation projectSlug={projectSlug} environment='production' />
+  );
+}
+
+ProductionPresentation.getLayout = (page) => <LayoutGuest>{page}</LayoutGuest>;
+```
+
+#### Stage Presentation
+
+**Location:** `pages/p/[projectSlug]/stage.tsx`
+**Route:** `/p/[slug]/stage`
+
+```typescript
+export default function StagePresentation() {
+  const router = useRouter();
+  const { projectSlug } = router.query;
+
+  return (
+    <RuntimePresentation projectSlug={projectSlug} environment='stage' />
+  );
+}
+
+StagePresentation.getLayout = (page) => <LayoutGuest>{page}</LayoutGuest>;
+```
+
+**Environment Distinction:**
+- `production` - Public, no auth required
+- `stage` - Preview, may require auth
+
+---
+
+### 7. Element Defaults Pages
+
+#### Global Element Type Defaults
+
+**Location:** `pages/element-type-defaults.tsx`
+**Route:** `/element-type-defaults`
+
+Lists all 11 global element type defaults.
+
+```typescript
+const ElementTypeDefaultsPage = () => {
+  const [rows, setRows] = useState([]);
+
+  useEffect(() => {
+    axios.get('/element-type-defaults?limit=1000').then((res) => {
+      setRows(res.data.rows);
+    });
+  }, []);
+
+  return (
+    <SectionMain>
+      <CardBox>
+        {rows.map((item) => (
+          <Link key={item.id} href={`/element-type-defaults/${item.id}`}>
+            <p>{item.name || toHumanLabel(item.element_type)}</p>
+            <p>{item.element_type} • Order {item.sort_order}</p>
+          </Link>
+        ))}
+      </CardBox>
+    </SectionMain>
+  );
+};
+
+ElementTypeDefaultsPage.getLayout = (page) => (
+  <LayoutAuthenticated permission='READ_PAGE_ELEMENTS'>{page}</LayoutAuthenticated>
+);
+```
+
+The page also links to `/global-transition-defaults` for transition defaults
+and lists global UI controls as separate items linking to per-control editors.
+
+#### Global Transition Defaults
+
+**Location:** `pages/global-transition-defaults.tsx`
+**Route:** `/global-transition-defaults`
+
+Dedicated editor for platform-wide page transition defaults.
+
+#### Global UI Control Defaults
+
+**Location:** `pages/global-ui-control-defaults.tsx`
+**Route:** `/global-ui-control-defaults`
+
+List page for platform-wide runtime controls. Each item opens a dedicated
+editor at `/global-ui-control-defaults/offline`,
+`/global-ui-control-defaults/fullscreen`, or
+`/global-ui-control-defaults/sound`. The editor uses `UiControlsSettingsForm`
+with General Settings, CSS Styles, and Effects tabs.
+
+#### Project Element Defaults
+
+**Location:** `pages/project-element-defaults.tsx`
+**Route:** `/project-element-defaults?projectId=X`
+
+Project-specific element defaults that override global defaults.
+
+#### Project UI Control Settings
+
+**Location:** `pages/project-ui-control-settings.tsx`
+**Route:** `/project-ui-control-settings?projectId=X&environment=dev`
+
+Dedicated editor for per-project fullscreen, sound, and offline control
+overrides. The form resolves global defaults as fallback, saves project
+environment overrides, and can remove the project override to return to global
+defaults.
+
+---
+
+### 8. Search Page
+
+**Location:** `pages/search.tsx`
+**Route:** `/search?query=X`
+
+Global search results page.
+
+```typescript
+const SearchView = () => {
+  const searchQuery = router.query.query;
+  const [searchResults, setSearchResults] = useState([]);
+
+  useEffect(() => {
+    axios.post('/search', { searchQuery }).then((res) => {
+      setSearchResults(res.data);
+    });
+  }, [searchQuery]);
+
+  // Group results by table
+  const groupedResults = searchResults.reduce((acc, item) => {
+    acc[item.tableName] = acc[item.tableName] || [];
+    acc[item.tableName].push(item);
+    return acc;
+  }, {});
+
+  return (
+    <SectionMain>
+      <CardBox>
+        <SearchResults searchResults={groupedResults} searchQuery={searchQuery} />
+      </CardBox>
+    </SectionMain>
+  );
+};
+
+SearchView.getLayout = (page) => (
+  <LayoutAuthenticated permission='CREATE_SEARCH'>{page}</LayoutAuthenticated>
+);
+```
+
+---
+
+### 9. API Routes
+
+Next.js API routes for server-side functionality.
+
+#### Error Logging (`api/logError.ts`)
+
+Stores runtime errors to JSON file for debugging.
+
+```typescript
+export default async function handler(req, res) {
+  const dataFilePath = path.join(process.cwd(), 'json/runtimeError.json');
+
+  if (req.method === 'GET') {
+    const jsonData = await fsPromises.readFile(dataFilePath, 'utf-8');
+    return res.status(200).json(JSON.parse(jsonData));
+  }
+
+  if (req.method === 'POST') {
+    await fsPromises.writeFile(dataFilePath, JSON.stringify(req.body));
+    return res.status(200).json({ message: 'Data stored successfully' });
+  }
+
+  if (req.method === 'DELETE') {
+    await fsPromises.writeFile(dataFilePath, '{}');
+    return res.status(200).json({ message: 'Data deleted successfully' });
+  }
+}
+```
+
+---
+
+### 10. Static Pages
+
+| Page | Route | Description |
+|------|-------|-------------|
+| `index.tsx` | `/` | Redirects guests to `/login` and authenticated users to `/projects/projects-list` |
+| `error.tsx` | `/error` | Error display page |
+| `privacy-policy.tsx` | `/privacy-policy` | Privacy policy text |
+| `terms-of-use.tsx` | `/terms-of-use` | Terms of use text |
+| `profile.tsx` | `/profile` | User profile edit |
+
+---
+
+## Layout System
+
+### getLayout Pattern
+
+Pages define their layout via a static `getLayout` property:
+
+```typescript
+// Authenticated page
+MyPage.getLayout = (page: ReactElement) => (
+  <LayoutAuthenticated permission='READ_USERS'>
+    {page}
+  </LayoutAuthenticated>
+);
+
+// Guest page (public)
+LoginPage.getLayout = (page: ReactElement) => (
+  <LayoutGuest>{page}</LayoutGuest>
+);
+
+// No layout (full-screen)
+RuntimePage.getLayout = (page: ReactElement) => page;
+```
+
+### Layout Components
+
+| Layout | Purpose | Features |
+|--------|---------|----------|
+| `LayoutAuthenticated` | Protected pages | JWT validation, permission check, NavBar, Sidebar, Footer |
+| `LayoutGuest` | Public pages | Minimal layout, no auth required |
+
+**LayoutAuthenticated Features:**
+- JWT token validation (client-side decode)
+- Permission checking per route
+- Project existence guard
+- NavBar with user menu
+- AsideMenu sidebar
+- FooterBar
+- IntroGuide tour integration
+
+---
+
+## Permission System
+
+Pages declare required permissions via layout:
+
+```typescript
+// Single permission
+<LayoutAuthenticated permission='READ_ASSETS'>{page}</LayoutAuthenticated>
+
+// Multiple permissions (any)
+<LayoutAuthenticated permissions={['READ_ASSETS', 'READ_PROJECTS']}>{page}</LayoutAuthenticated>
+
+// No permission required (authenticated only)
+<LayoutAuthenticated>{page}</LayoutAuthenticated>
+```
+
+**Permission Naming Convention:**
+- `READ_[ENTITY]` - View list/details
+- `CREATE_[ENTITY]` - Create new records
+- `UPDATE_[ENTITY]` - Edit existing records
+- `DELETE_[ENTITY]` - Delete records
+
+---
+
+## Factory Pattern
+
+### createListPage Factory
+
+Generates standardized list pages with common functionality.
+
+**Input:**
+
+```typescript
+interface ListPageConfig {
+  entityName: string;          // API endpoint name
+  entityTitle: string;         // Page title
+  TableComponent: Component;   // Table component
+  filters: Filter[];           // Available filters
+  readPermission: string;      // Required permission
+  createPermission: string;    // For "New" button
+  uploadCsvAction: AsyncThunk; // CSV upload action
+  setRefetchAction: Action;    // Trigger refetch
+  newItemLabel?: string;       // "New Item" button label
+  cardBoxId?: string;          // For tour targeting
+}
+```
+
+**Generated Output:**
+- Page component with title
+- "New Item" button (permission-checked)
+- Filter button and filter rows
+- CSV download/upload buttons
+- Table component with pagination
+- Layout with permission check
+
+---
+
+## Page File Reference
+
+### By Size (Largest First)
+
+| File | Size | Description |
+|------|------|-------------|
+| `constructor.tsx` | 1515 LOC | Visual tour builder |
+| `projects/projects-view.tsx` | 827 LOC | Project view with all relations |
+| `_app.tsx` | 324 LOC | App entry point |
+| `privacy-policy.tsx` | 292 LOC | Legal page |
+| `login.tsx` | 230 LOC | Authentication |
+| `terms-of-use.tsx` | 205 LOC | Legal page |
+| `dashboard.tsx` | 203 LOC | Admin home |
+| `project-element-defaults.tsx` | 199 LOC | Project defaults |
+| `profile.tsx` | 182 LOC | User profile |
+| `projects/[projectsId].tsx` | 354 LOC | Project workspace |
+| `project-ui-control-settings.tsx` | 226 LOC | Project UI controls |
+| `element-type-defaults.tsx` | 277 LOC | Defaults hub |
+| `global-transition-defaults.tsx` | 221 LOC | Global transition defaults |
+| `global-ui-control-defaults/[controlType].tsx` | 153 LOC | Single global UI control |
+| `global-ui-control-defaults.tsx` | 103 LOC | Global UI controls list |
+| `search.tsx` | 97 LOC | Search results |
+| `index.tsx` | 25 LOC | Root redirect |
+| `forgot.tsx` | 85 LOC | Password reset |
+
+### By Category
+
+| Category | Files | Total LOC |
+|----------|-------|-----------|
+| Entity CRUD | 78 | ~4000 |
+| Authentication | 4 | ~400 |
+| Special Pages | 10 | ~3100 |
+| Static/Legal | 4 | ~600 |
+| API Routes | 2 | ~100 |
+| Runtime | 2 | ~60 |
+| App Entry | 1 | ~324 |
+| Element Defaults | 8 | ~1100 |
+
+---
+
+## Routing Reference
+
+### Static Routes
+
+| Route | Page | Layout | Permission |
+|-------|------|--------|------------|
+| `/` | index.tsx | Guest | Redirect entry |
+| `/login` | login.tsx | Guest | - |
+| `/forgot` | forgot.tsx | Guest | - |
+| `/verify-email` | verify-email.tsx | Guest | - |
+| `/password-reset` | password-reset.tsx | Guest | - |
+| `/dashboard` | dashboard.tsx | Authenticated | - |
+| `/profile` | profile.tsx | Authenticated | - |
+| `/search` | search.tsx | Authenticated | CREATE_SEARCH |
+| `/error` | error.tsx | Guest | - |
+| `/constructor` | constructor.tsx | Authenticated | UPDATE_TOUR_PAGES |
+| `/element-type-defaults` | element-type-defaults.tsx | Authenticated | READ_PAGE_ELEMENTS |
+| `/global-transition-defaults` | global-transition-defaults.tsx | Authenticated | UPDATE_PAGE_ELEMENTS |
+| `/global-ui-control-defaults` | global-ui-control-defaults.tsx | Authenticated | READ_PAGE_ELEMENTS |
+| `/project-element-defaults` | project-element-defaults.tsx | Authenticated | READ_PAGE_ELEMENTS |
+| `/project-ui-control-settings` | project-ui-control-settings.tsx | Authenticated | UPDATE_PAGE_ELEMENTS |
+| `/privacy-policy` | privacy-policy.tsx | Guest | - |
+| `/terms-of-use` | terms-of-use.tsx | Guest | - |
+
+### Dynamic Routes
+
+| Route Pattern | Page | Description |
+|---------------|------|-------------|
+| `/p/[projectSlug]` | p/[projectSlug]/index.tsx | Production presentation |
+| `/p/[projectSlug]/stage` | p/[projectSlug]/stage.tsx | Stage presentation |
+| `/global-ui-control-defaults/[controlType]` | global-ui-control-defaults/[controlType].tsx | Single global UI control editor |
+| `/[entity]/[entityId]` | [entity]/[entityId].tsx | Entity workspace/redirect |
+
+### Entity Routes (×13)
+
+| Entity | List | New | Edit | View |
+|--------|------|-----|------|------|
+| users | `/users/users-list` | `/users/users-new` | `/users/users-edit?id=X` | `/users/users-view?id=X` |
+| roles | `/roles/roles-list` | ... | ... | ... |
+| permissions | `/permissions/permissions-list` | ... | ... | ... |
+| projects | `/projects/projects-list` | ... | ... | ... |
+| project_memberships | `/project_memberships/...` | ... | ... | ... |
+| assets | `/assets/assets-list` | ... | ... | ... |
+| asset_variants | `/asset_variants/...` | ... | ... | ... |
+| presigned_url_requests | `/presigned_url_requests/...` | ... | ... | ... |
+| tour_pages | `/tour_pages/tour_pages-list` | ... | ... | ... |
+| project_audio_tracks | `/project_audio_tracks/...` | ... | ... | ... |
+| publish_events | `/publish_events/...` | ... | ... | ... |
+| pwa_caches | `/pwa_caches/pwa_caches-list` | ... | ... | ... |
+| access_logs | `/access_logs/access_logs-list` | ... | ... | ... |
+
+---
+
+## Common Patterns
+
+### 1. Page with Formik Form
+
+```typescript
+import { Formik, Form, Field } from 'formik';
+
+const MyPage = () => {
+  const handleSubmit = async (values) => {
+    await dispatch(create(values));
+    router.push('/entity/entity-list');
+  };
+
+  return (
+    <Formik initialValues={{...}} onSubmit={handleSubmit}>
+      <Form>
+        <FormField label='Name'>
+          <Field name='name' />
+        </FormField>
+        <BaseButton type='submit' label='Submit' />
+      </Form>
+    </Formik>
+  );
+};
+```
+
+### 2. Page with Data Fetching
+
+```typescript
+const MyPage = () => {
+  const dispatch = useAppDispatch();
+  const data = useAppSelector((state) => state.entity.items);
+  const { id } = router.query;
+
+  useEffect(() => {
+    dispatch(fetch({ id }));
+  }, [id]);
+
+  return <div>{data?.name}</div>;
+};
+```
+
+### 3. Page with useEditPageSync
+
+```typescript
+const EditPage = () => {
+  const { values, setValues, id } = useEditPageSync({
+    entitySelector: (state) => state.entity.items,
+    fetchAction: fetch,
+    initialValues: { name: '', ... },
+  });
+
+  return (
+    <Formik enableReinitialize initialValues={values} ...>
+      ...
+    </Formik>
+  );
+};
+```
+
+### 4. Page with Permission Check
+
+```typescript
+MyPage.getLayout = (page) => (
+  <LayoutAuthenticated permission='READ_ENTITY'>
+    {page}
+  </LayoutAuthenticated>
+);
+```
+
+---
+
+## Related Documentation
+
+| Document | Description |
+|----------|-------------|
+| [frontend-architecture.md](./frontend-architecture.md) | Overall frontend architecture |
+| [hooks-reference.md](./hooks-reference.md) | Custom hooks documentation |
+| [runtime-presentation.md](./runtime-presentation.md) | Runtime presentation details |
+| [constructor-page-editor.md](./constructor-page-editor.md) | Constructor page details |
+| [ui-elements.md](../../documentation/ui-elements.md) | UI element types |
diff --git a/frontend/docs/runtime-presentation.md b/frontend/docs/runtime-presentation.md
new file mode 100644
index 0000000..a7944fe
--- /dev/null
+++ b/frontend/docs/runtime-presentation.md
@@ -0,0 +1,1531 @@
+# Runtime Presentation Page - E2E Documentation
+
+## Overview
+
+The Runtime Presentation system is a full-screen, presentation-mode viewer for virtual tours. It enables end users to navigate through tour pages with transitions, rich media content, and offline support. Unlike the Constructor (edit mode), Runtime is optimized for public viewing with intelligent preloading and smooth transitions.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       Access Routes                              │
+│  /p/[projectSlug] │ /p/[projectSlug]/stage │ /runtime           │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                   RuntimePresentation Component                  │
+│  Page Rendering │ Navigation │ Transitions │ Offline Support    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                       Hooks Layer                                │
+│  usePageDataLoader │ useProjectAssets │ usePreloadOrchestrator  │
+│  usePageSwitch │ useTransitionPlayback │ useBackgroundTransition│
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Component Layer                              │
+│  RuntimeElement │ UiElementRenderer │ GalleryCarouselOverlay    │
+│  RuntimeControls (Offline + Fullscreen + Sound)                 │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                     Helper Libraries                             │
+│  extractPageLinks │ navigationHelpers │ assetUrl │ logger       │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                       Data Layer                                 │
+│  Projects API │ Tour Pages API │ S3 Direct Download              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Access Modes
+
+### Production Mode
+
+**Route:** `/p/[projectSlug]`
+
+- Public access without authentication
+- Shows only production environment pages
+- Full offline support with OfflineToggle
+
+### Stage Mode
+
+**Route:** `/p/[projectSlug]/stage`
+
+- Testing environment for previewing changes before production
+- Shows only `stage` environment pages
+- Environment badge displayed
+- Content published from Constructor via "Save to Stage" button
+
+### Admin Runtime Mode
+
+**Route:** `/runtime`
+
+- Internal admin testing
+- Requires authentication
+- Can test any project
+
+### Environment Model
+
+Content flows through three environments:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Constructor (Edit)     Stage (Preview)      Production (Live)  │
+│       dev        ──────►   stage      ──────►   production      │
+│  "Save to Stage"        "Publish"                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+| Environment | Purpose | Access |
+|-------------|---------|--------|
+| `dev` | Active editing in Constructor | Constructor only (not Runtime) |
+| `stage` | Preview/testing before publish | `/p/[slug]/stage` route |
+| `production` | Live public presentation | `/p/[slug]` route |
+
+**Note:** The `dev` environment is only accessible in the Constructor. Runtime always shows either `stage` or `production` content.
+
+---
+
+## Runtime Context Detection
+
+**Primary Method: Route-Based Environment**
+
+The platform uses **route-based environment access**, not subdomains. The environment is determined by the frontend route and passed to the backend via headers.
+
+| Route | Environment | Component |
+|-------|-------------|-----------|
+| `/p/[projectSlug]` | production | `pages/p/[projectSlug]/index.tsx` |
+| `/p/[projectSlug]/stage` | stage | `pages/p/[projectSlug]/stage.tsx` |
+
+**Frontend sends environment via headers:**
+
+```typescript
+// RuntimePresentation.tsx
+const apiConfig = {
+  headers: {
+    'X-Runtime-Project-Slug': projectSlug,
+    'X-Runtime-Environment': environment,  // 'production' | 'stage'
+  },
+};
+```
+
+**Backend middleware** (`middleware/runtime-context.ts`):
+
+```javascript
+// Reads both hostname AND headers for flexibility
+req.runtimeContext = {
+  mode: detectFromHostname(hostname),       // Fallback for subdomain access
+  headerEnvironment: req.headers['x-runtime-environment'],
+  headerProjectSlug: req.headers['x-runtime-project-slug'],
+};
+```
+
+**Backend DB filtering** (`db/api/runtime-context.ts`):
+
+```javascript
+// Uses header-based environment when hostname detection returns 'admin'
+// SECURITY: Only 'production' and 'stage' allowed from headers
+// 'dev' is blocked to prevent unauthorized access to dev data
+```
+
+---
+
+## Project Loading
+
+### useProjectAssets Hook
+
+The component uses the `useProjectAssets` hook to resolve project assets (favicon, og_image) to presigned URLs for meta tags:
+
+```typescript
+// Resolve project assets (favicon, og_image, logo) to presigned URLs
+const { faviconUrl, ogImageUrl } = useProjectAssets(project);
+```
+
+This hook:
+- Extracts storage paths from URLs (handles both `storage_key` and legacy `cdn_url` formats)
+- Queues presigned URL requests for relative paths
+- Resolves to playback URLs (presigned if available, otherwise proxy)
+
+### Global UI Controls
+
+Runtime controls for offline mode, fullscreen, and global sound mute resolve
+through `global_ui_control_defaults`, `project_ui_control_settings`, and the
+current page's `global_ui_controls_settings_json`. Dimensions and positions use
+canvas-relative percentages, so controls keep consistent proportions and spacing
+across screens for projects with the same canvas ratio.
+
+Custom icons use each control's `defaultIconUrl` and `activeIconUrl`; empty
+values fall back to the built-in MDI icons.
+Embedded runtime fullscreen uses the same wrapper fallback as Info Panel image
+detail fullscreen: native document fullscreen first, same-origin iframe
+fullscreen second, then parent `tour-builder:request-fullscreen` postMessage.
+Exit from cross-origin wrapper fullscreen posts `tour-builder:exit-fullscreen`.
+
+### usePageDataLoader Hook
+
+The component uses the shared `usePageDataLoader` hook for data loading:
+
+```typescript
+const { project, pages, isLoading, error, initialPageId } = usePageDataLoader({
+  projectSlug,
+  environment,
+  apiHeaders: {
+    'X-Runtime-Project-Slug': projectSlug,
+    'X-Runtime-Environment': environment,
+  },
+});
+```
+
+### Data Fetching Flow
+
+```
+1. usePageDataLoader fetches project
+   └── GET /projects?slug={projectSlug}
+   └── Headers: X-Runtime-Project-Slug, X-Runtime-Environment
+
+2. usePageDataLoader fetches tour pages
+   └── GET /tour_pages?project={projectId}
+   └── Pages include ui_schema_json with navigation elements
+
+3. STRICT environment filtering (both layers)
+   └── Backend: Filters by X-Runtime-Environment header
+   └── Frontend: .filter((p) => p.environment === environment)
+
+4. Pages sorted by sort_order
+
+5. initialPageId returned (first page by sort_order)
+```
+
+**Note:** Navigation targets, transitions, and page elements are all stored in `tour_pages.ui_schema_json`. No separate API calls needed.
+
+### Environment Isolation (Critical)
+
+**IMPORTANT:** Strict environment filtering prevents data leaks.
+
+**Frontend Filter** (`RuntimePresentation.tsx`):
+
+```typescript
+// STRICT: Only exact environment match - no fallbacks!
+const envFilteredPages = pageRows
+  .filter((p: any) => p.environment === environment)
+  .sort((a: any, b: any) => (a.sort_order ?? 0) - (b.sort_order ?? 0));
+```
+
+**Backend Filter** (`db/api/runtime-context.ts`):
+
+```javascript
+// Header-based filtering for route-based access
+// Only 'production' and 'stage' allowed - 'dev' is BLOCKED
+if (runtimeContext.headerEnvironment === 'production') return 'production';
+if (runtimeContext.headerEnvironment === 'stage') return 'stage';
+```
+
+| Route | Shows | Never Shows |
+|-------|-------|-------------|
+| `/p/cardiff` | `environment='production'` only | dev, stage |
+| `/p/cardiff/stage` | `environment='stage'` only | dev, production |
+
+### Public Runtime Headers
+
+```typescript
+const headers = {
+  'X-Runtime-Project-Slug': projectSlug,
+  'X-Runtime-Environment': environment,  // 'production' | 'stage'
+};
+```
+
+### Public Field Filtering
+
+The `runtime-public.ts` middleware sanitizes responses for unauthenticated requests:
+
+**Projects:** id, name, slug, description, logo_url, favicon_url, og_image_url
+
+**Tour Pages:** id, projectId, environment, source_key, name, slug, sort_order, background_image_url, background_video_url, background_embed_url, background_audio_url, background_loop, requires_auth, ui_schema_json
+
+**Project Audio Tracks:** id, projectId, environment, source_key, name, slug, url, loop, volume, sort_order, is_enabled
+
+**Note:** Navigation links and transitions are stored in `tour_pages.ui_schema_json`, not as separate entities.
+
+### Transition Settings (Public Access)
+
+The RuntimePresentation fetches transition settings from two endpoints:
+
+```typescript
+// On mount - fetch global defaults (always public)
+useEffect(() => {
+  dispatch(fetchGlobalTransitionDefaults());
+}, [dispatch]);
+
+// When project loads - fetch project-specific settings
+useEffect(() => {
+  if (project?.id) {
+    dispatch(fetchProjectTransitionSettings({
+      projectId: project.id,
+      environment,
+      apiHeaders: runtimeApiHeaders,
+    }));
+  }
+}, [dispatch, project?.id, environment, runtimeApiHeaders]);
+```
+
+**Authentication Model (URL-path based):**
+
+| Endpoint | Environment | Auth Required |
+|----------|-------------|---------------|
+| `GET /global-transition-defaults` | n/a | **No** (always public) |
+| `GET /project-transition-settings/project/:id/env/production` | production | No for public projects; JWT + staff permission or DB access grant for private projects |
+| `GET /project-transition-settings/project/:id/env/stage` | stage | Yes |
+
+Public presentations (`/p/[slug]`) work in incognito mode without authentication.
+Private production presentations use the same runtime route, but require JWT and
+the project visibility/access grant flow described in
+[private-production-presentations.md](../../documentation/private-production-presentations.md).
+
+---
+
+## Page Rendering
+
+### Z-Index Layering Structure
+
+The RuntimePresentation uses a specific z-index hierarchy to ensure proper layering of components:
+
+| Layer | Z-Index | Component | Purpose |
+|-------|---------|-----------|---------|
+| Background | `z-1` | Background image/video | Page background content |
+| Backdrop blur | `z-5` | BackdropPortalProvider | Blur effects for elements |
+| Carousel background | `z-10` | CarouselElement (portal) | Full-width carousel background |
+| Previous background | `z-10` | Previous bg overlay | Shows during page transitions |
+| Carousel controls | `z-30` | CarouselElement (portal) | Carousel prev/next buttons |
+| **Page elements** | **`z-40`** | Elements container | Navigation buttons, UI elements |
+| UI controls | settings-driven | RuntimeControls | Canvas-relative global controls |
+| Transition overlay | `z-50` | Transition video | Page transition videos |
+
+**Key Design Decisions:**
+- Page elements at `z-40` ensures they appear above carousel controls (`z-30`) for proper click handling
+- Carousel uses portals to `document.body` with `position: fixed` for full-screen display
+- Carousel wrappers have `pointer-events-none` with buttons having `pointer-events-auto`
+- Background video at `z-1` keeps it below backdrop blur effects
+
+### RuntimeControls Component
+
+**Location:** `src/components/Runtime/RuntimeControls.tsx`
+
+The RuntimeControls component renders the offline toggle, fullscreen button,
+and optional global sound button. Each button has independent canvas-relative
+positioning, dimensions, styling, order, visibility, disabled state, and
+state-specific icon/color settings. The sound button is presentation-level: if
+any page in the loaded runtime environment has background audio, unmuted
+background video, hover/click effects, media player sound, or
+gallery/info-panel video, the button is visible on every page in that
+presentation.
+
+**Key Features:**
+
+| Feature | Implementation |
+|---------|----------------|
+| Canvas-relative positioning | `xPercent`/`yPercent` are resolved inside the visible canvas bounds |
+| Canvas-relative sizing | `buttonSizePercent`, `iconSizePercent`, and `borderRadiusPercent` resolve from canvas width |
+| Pinch-zoom resistance | Uses `visualViewport` API to counter-scale during pinch-zoom |
+| Configurable z-index | Runtime uses control settings; constructor clamps controls below editor chrome |
+| Global sound toggle | Uses `presentationHasAudio`, `useVideoSoundControl`, and `backgroundAudioController` to mute/unmute background audio, hover/click effects, audio/video player elements, and gallery/info-panel videos across the whole presentation |
+| Optional controls | `showOfflineButton`, `showFullscreenButton`, and `showSoundButton` gate rendering without deleting settings |
+
+**iOS Pinch-Zoom Fix:**
+
+iOS browsers (all use WebKit engine) have inconsistent scaling behavior between `rem` units and other CSS values during pinch-zoom gestures. The RuntimeControls uses a `useCounterZoom` hook that:
+
+1. Listens to `visualViewport.resize` and `visualViewport.scroll` events
+2. Reads `visualViewport.scale` to detect current pinch-zoom level
+3. Applies an inverse `transform: scale(1/zoomLevel)` to maintain constant visual size
+
+```typescript
+// Counter-scale formula
+const counterScale = 1 / visualViewport.scale;
+// Applied as: transform: scale(counterScale), transformOrigin: 'top right'
+```
+
+**Sub-components:**
+- `ControlButton` - Styled button with hover states matching BaseButton colors
+- `ControlIcon` - built-in SVG or custom asset icon renderer
+- `OfflineControl` - Offline download toggle with status indicators
+
+### UI Schema Structure
+
+Pages store elements in `ui_schema_json`:
+
+```typescript
+interface UISchema {
+  elements: UISchemaElement[];
+}
+
+interface UISchemaElement {
+  id: string;
+  type: ElementType;
+
+  // Position (percentage-based)
+  xPercent: number;
+  yPercent: number;
+  rotation?: number;
+
+  // Dimensions
+  width?: string;
+  height?: string;
+
+  // Styling
+  opacity?: number;
+  padding?: string;
+  margin?: string;
+  fontSize?: string;
+  fontFamily?: string;
+  color?: string;
+  backgroundColor?: string;
+
+  // Content
+  iconUrl?: string;
+  imageUrl?: string;
+  mediaUrl?: string;
+
+  // Navigation (stored in ui_schema_json)
+  targetPageSlug?: string;  // Slug-based navigation (consistent across environments)
+  navType?: 'forward' | 'back';
+  navLabel?: string;
+  navDisabled?: boolean;    // Runtime ignores activation while preserving visual effects
+  transitionVideoUrl?: string;
+
+  // Type-specific
+  descriptionTitle?: string;
+  descriptionText?: string;
+  tooltipTitle?: string;
+  tooltipText?: string;
+  galleryCards?: GalleryCard[];
+  carouselSlides?: CarouselSlide[];
+}
+```
+
+### Element Rendering
+
+Elements are rendered using shared components for WYSIWYG consistency with the constructor:
+
+```tsx
+{/* Page elements - z-40 ensures they appear above carousel controls (z-30) */}
+<div className="absolute inset-0 z-40">
+  {pageElements.map((element: CanvasElement) => (
+    <RuntimeElement
+      key={element.id}
+      element={element}
+      onClick={() => handleElementClick(element)}
+      resolveUrl={resolveUrlWithBlob}
+      onGalleryCardClick={(cardIndex) => handleGalleryCardClick(element, cardIndex)}
+    />
+  ))}
+</div>
+
+// URL resolver uses preloaded blob URLs when available (instant display)
+const resolveUrlWithBlob = useCallback(
+  (url: string | undefined): string => {
+    if (!url) return '';
+    // Try storage key first, then resolved URL
+    const blobUrl =
+      preloadOrchestrator?.getReadyBlobUrl(url) ||
+      preloadOrchestrator?.getReadyBlobUrl(resolveAssetPlaybackUrl(url));
+    if (blobUrl) return blobUrl;
+    return resolveAssetPlaybackUrl(url);
+  },
+  [preloadOrchestrator],
+);
+```
+
+**Component Architecture:**
+- `RuntimeElement` handles positioning, rotation, and interactive effects (hover/focus/active)
+- `RuntimeElement` delegates content rendering to `UiElementRenderer`
+- `UiElementRenderer` delegates to per-type components (NavigationElement, GalleryElement, etc.)
+- Both Constructor (`CanvasElement`) and Runtime (`RuntimeElement`) use `UiElementRenderer` for WYSIWYG consistency
+
+### RuntimeElement Component
+
+Wraps each UI element with positioning, interactive effects, and delegates content rendering to `UiElementRenderer`:
+
+| Feature | Description |
+|---------|-------------|
+| **Percentage positioning** | Uses `xPercent`, `yPercent` for responsive placement |
+| **Transform** | Centers element and applies rotation |
+| **Interactive effects** | Hover, focus, and active state styling via `useElementEffects` hook |
+| **Click handling** | Propagates clicks to parent handler; disabled navigation/info panel elements keep visual hover/focus/active effects but ignore click and keyboard activation |
+| **Gallery card clicks** | `onGalleryCardClick` prop opens GalleryCarouselOverlay |
+| **Content delegation** | Renders content via `UiElementRenderer` for WYSIWYG consistency |
+| **URL resolution** | Passes `resolveUrl` prop for blob URL support |
+
+### UiElementRenderer Component
+
+Unified element rendering component - single source of truth used by both `RuntimeElement` (presentation) and `CanvasElement` (constructor) for WYSIWYG consistency.
+
+**Architecture:**
+```
+UiElementRenderer (main entry point)
+├── useElementWrapperStyle (shared styling hook)
+└── Per-type components:
+    ├── NavigationElement (navigation_next, navigation_prev)
+    ├── GalleryElement (gallery) → can trigger GalleryCarouselOverlay
+    ├── TooltipElement (tooltip)
+    ├── DescriptionElement (description)
+    ├── CarouselElement (carousel)
+    ├── LogoElement (logo)
+    ├── SpotElement (spot/hotspot)
+    ├── VideoPlayerElement (video_player)
+    ├── AudioPlayerElement (audio_player)
+    └── PopupElement (popup)
+
+GalleryCarouselOverlay (fullscreen overlay)
+├── Swipe navigation between images
+├── Customizable prev/next/back buttons
+└── Percentage-based button positioning
+```
+
+| Element Type | Component | Rendered Content |
+|--------------|-----------|------------------|
+| `navigation_*` | NavigationElement | Icon + label with nav styling |
+| `spot` | SpotElement | Hotspot/clickable area with icon |
+| `description` | DescriptionElement | Title + text block |
+| `tooltip` | TooltipElement | Icon with popover |
+| `video_player` | VideoPlayerElement | HTML5 video |
+| `audio_player` | AudioPlayerElement | HTML5 audio |
+| `gallery` | GalleryElement | Image grid from galleryCards |
+| `carousel` | CarouselElement | Slideshow from carouselSlides |
+| `logo` | LogoElement | Logo image element |
+| `popup` | PopupElement | Modal/popup overlay |
+
+### Element Types
+
+| Type | Rendering |
+|------|-----------|
+| `navigation_next` | Button with icon, navigates forward |
+| `navigation_prev` | Button with icon, navigates backward |
+| `spot` | Hotspot/clickable area with icon |
+| `description` | Title + text block with styling |
+| `tooltip` | Icon with hover popover |
+| `video_player` | HTML5 video with controls |
+| `audio_player` | HTML5 audio with controls |
+| `gallery` | Grid of images from galleryCards |
+| `carousel` | Slideshow from carouselSlides |
+| `logo` | Logo image element |
+| `popup` | Modal/popup overlay |
+
+---
+
+## Page Navigation
+
+### Navigation Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1. User clicks navigation element                               │
+│     └── handleElementClick(element)                              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  2. Extract navigation data & resolve slug                       │
+│     └── targetPageSlug → resolve to targetPageId                 │
+│     └── navType, transitionVideoUrl                              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  3. Determine if back navigation                                 │
+│     └── navType === 'back' OR type === 'navigation_prev'        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  4. Wait for target page images                                  │
+│     └── Decode images to prevent white flash                     │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+          ┌───────────────────┴───────────────────┐
+          │                                       │
+          ▼                                       ▼
+┌──────────────────────┐              ┌──────────────────────┐
+│  Has Transition?     │              │  No Transition       │
+│  YES                 │              │  Direct page switch  │
+└──────────┬───────────┘              └──────────────────────┘
+           │
+           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  5. Show transition overlay via useTransitionPlayback            │
+│     └── Full-screen video playback (forward or reverse)          │
+│     └── Images pre-decode DURING video playback                  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  6. Video ends → onComplete callback fires                       │
+│     └── waitForPageImages() completes instantly (pre-decoded)    │
+│     └── Switch to target page                                    │
+│     └── Update page history                                      │
+│     └── Double requestAnimationFrame ensures page painted        │
+│     └── THEN remove overlay (setTransitionPreview(null))         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Element Click Handler
+
+The click handler uses shared navigation helpers from `lib/navigationHelpers.ts`:
+
+```typescript
+const handleElementClick = useCallback(
+  (element: any) => {
+    if (isNavigationType(element.type) && element.navDisabled) {
+      return;
+    }
+
+    // Block navigation while transition is actively playing or buffering
+    if (isTransitionBlocking(transitionPhase as TransitionPhase, isBuffering)) {
+      return;
+    }
+
+    // Use shared helper to resolve navigation target
+    const navTarget = resolveNavigationTarget(element, pages);
+
+    if (navTarget) {
+      navigateToPage(
+        navTarget.pageId,
+        navTarget.transitionVideoUrl,
+        navTarget.isBack,
+      );
+    }
+  },
+  [navigateToPage, pages, transitionPhase, isBuffering],
+);
+```
+
+### Navigation Helpers (`lib/navigationHelpers.ts`)
+
+| Helper | Purpose |
+|--------|---------|
+| `resolveNavigationTarget(element, pages)` | Resolves element's `targetPageSlug` to page ID, returns `{pageId, transitionVideoUrl, isBack}` or `null` |
+| `isTransitionBlocking(phase, isBuffering)` | Returns `true` if navigation should be blocked (transition playing) |
+| `getNavigationDirection(element)` | Returns `'forward'` or `'back'` based on `navType` or element type |
+
+**Note:** Navigation elements store `targetPageSlug` (not UUID) because slugs are consistent across environments (dev/stage/production). The slug is resolved to a page ID at navigation time.
+
+### Page History Management
+
+Page history is now managed by the shared `usePageNavigation` hook (replacing manual `useState`):
+
+```typescript
+// usePageNavigation hook provides unified history management
+const {
+  currentPageId: selectedPageId,
+  pageHistory,
+  applyPageSelection,
+  getNavigationContext,
+} = usePageNavigation({
+  pages,
+  defaultPageId: initialPageId,
+  trackHistory: true,
+});
+
+// applyPageSelection handles history with browser-like behavior:
+// - Forward: appends to history (trimmed to MAX_HISTORY_LENGTH=50)
+// - Back (isBack=true): pops from history if target matches previous page
+applyPageSelection(targetPageId, isBack);
+
+// getNavigationContext provides context for history-based navigation
+const navContext = getNavigationContext();
+// Returns: { currentPageSlug, previousPageId }
+const navTarget = resolveNavigationTarget(element, pages, navContext);
+```
+
+---
+
+## Transition Execution
+
+### Transition State
+
+```typescript
+// Transition state for useTransitionPlayback hook
+const [transitionPreview, setTransitionPreview] = useState<{
+  targetPageId: string;
+  videoUrl: string;      // Resolved URL for playback
+  storageKey: string;    // Raw storage path for cache lookup (enables presigned URL independence)
+  isReverse: boolean;
+} | null>(null);
+```
+
+### useTransitionPlayback Hook Integration
+
+The `useTransitionPlayback` hook handles both forward and reverse playback with smooth transitions:
+
+```typescript
+// State for coordinating transition completion with background readiness
+const [isBackgroundReady, setIsBackgroundReady] = useState(true);
+const [pendingTransitionComplete, setPendingTransitionComplete] = useState(false);
+
+// Hook returns both isBuffering and phase for granular opacity control
+const { isBuffering, phase: transitionPhase } = useTransitionPlayback({
+  videoRef: transitionVideoRef,
+  transition: transitionPreview
+    ? {
+        videoUrl: transitionPreview.videoUrl,
+        storageKey: transitionPreview.storageKey,  // Raw path for instant cache lookup
+        reverseMode: transitionPreview.isReverse ? 'reverse' : 'none',
+        targetPageId: transitionPreview.targetPageId,
+        displayName: 'Transition',
+        isBack: transitionPreview.isReverse,  // Pass through for history management
+      }
+    : null,
+  // onComplete receives isBack flag for proper history management
+  onComplete: async (targetPageId, isBack) => {
+    if (targetPageId) {
+      const targetPage = pages.find((p) => p.id === targetPageId);
+      // Use shared hook to resolve blob URLs and switch page
+      await pageSwitch.switchToPage(targetPage, () => {
+        // usePageNavigation hook: pops history on back, appends on forward
+        applyPageSelection(targetPageId, isBack ?? false);
+      });
+      setIsBackgroundReady(false);
+      // Signal transition complete, wait for background
+      setPendingTransitionComplete(true);
+    } else {
+      // Cleanup when no target page
+      video?.removeAttribute('src');
+      video?.load();
+      setTransitionPreview(null);
+      setPendingTransitionComplete(false);
+    }
+  },
+  features: {
+    useBlobUrl: true,         // Enables seeking for reverse playback
+    preDecodeImages: false,   // Overlay shows last frame while new bg loads behind
+  },
+  preload: {
+    preloadedUrls: preloadOrchestrator?.preloadedUrls || new Set(),
+    getCachedBlobUrl: preloadOrchestrator?.getCachedBlobUrl,
+    getReadyBlobUrl: preloadOrchestrator?.getReadyBlobUrl,  // Instant O(1) lookup by storage key
+  },
+});
+```
+
+### useBackgroundTransition Hook Integration
+
+The `useBackgroundTransition` hook handles crossfade effects for **non-video navigation only**:
+
+```typescript
+// Use shared background transition hook for crossfade effects
+// NOTE: fadeOut config is NOT used for video transitions.
+// Video transitions end instantly (last frame = new page, then overlay removed).
+// fadeIn is used for non-video navigation (crossfade 700ms).
+const { isFadingIn, onFadeInAnimationEnd, resetFadeIn } =
+  useBackgroundTransition({
+    pageSwitch,
+    // No fadeOut - video transitions don't use fade
+    fadeIn: {
+      hasActiveTransition: Boolean(transitionPreview),
+    },
+  });
+```
+
+**Video Overlay Removal (separate effect, no hook involvement):**
+```typescript
+// Video transition overlay removal - instant (no fade) when background is ready
+useEffect(() => {
+  if (pendingTransitionComplete && isBackgroundReady) {
+    const video = transitionVideoRef.current;
+    if (video) {
+      video.removeAttribute('src');
+      video.load();
+    }
+    setTransitionPreview(null);
+    setPendingTransitionComplete(false);
+  }
+}, [pendingTransitionComplete, isBackgroundReady]);
+```
+
+**How it works (instant removal, no fade):**
+1. When `pendingTransitionComplete && isBackgroundReady`, effect triggers cleanup
+2. **Instant** overlay removal (no fade animation):
+   - `video.removeAttribute('src'); video.load()` - cleanup video
+   - `setTransitionPreview(null)` - removes overlay immediately
+   - `setPendingTransitionComplete(false)` - reset state
+
+**Why no fade for video transitions:**
+- Video itself IS the transition effect
+- First frame of video = old page background
+- Last frame of video = new page background
+- Fading would create visual discontinuity
+
+### Transition Overlay Rendering
+
+```tsx
+{/* Container hidden while buffering to prevent black flash */}
+{/* Video first frame should match old page background */}
+{/* Overlay removed instantly when new background ready */}
+{transitionPreview && (
+  <TransitionPreviewOverlay
+    videoRef={transitionVideoRef}
+    isActive={true}
+    isBuffering={transitionPhase === 'preparing' || isBuffering}
+    letterboxStyles={letterboxStyles}
+    opacity={1}  // Always 1 - no fade-out for video transitions
+  />
+)}
+```
+
+**TransitionPreviewOverlay behavior:**
+- `containerOpacity = isBuffering ? 0 : 1` - hides entire container while loading
+- Old page visible through transparent overlay until video ready
+- Video appears instantly when ready (first frame = old page)
+- Overlay removed instantly when new background ready
+
+### Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Container hidden while buffering** | Prevents black flash, old page visible |
+| **Instant overlay appearance** | Video first frame matches old page |
+| **Instant overlay removal** | No fade-out, removed when bg ready |
+| **useBackgroundTransition** | Shared hook handles crossfade (non-video nav) |
+| **isBackgroundReady state** | Tracks when new page background is fully rendered |
+| **pendingTransitionComplete state** | Signals video ended, waiting for background |
+| **Blob URL support** | Enables seeking for reverse playback |
+| **Video cleanup** | `removeAttribute('src')` + `load()` prevents memory leaks |
+| **Navigation blocking** | `isTransitionBlocking()` prevents navigation during playback |
+
+### Reverse Playback Modes
+
+The hook internally uses `useReversePlayback` with strategies:
+
+1. **Native Reverse** - `video.playbackRate = -1` (Chrome, Edge)
+2. **Frame-Stepping** - Manual frame-by-frame reverse (Safari, Firefox)
+
+---
+
+## Background Media
+
+### Background Image
+
+The background uses both CSS `background-image` (for immediate display) and an image element for proper loading detection. **Blob URLs use native `<img>` to prevent re-fetch issues, while regular URLs use Next.js Image:**
+
+```tsx
+<div
+  className="relative w-screen h-screen overflow-hidden bg-black"
+  style={{
+    backgroundImage: backgroundImageUrl ? `url("${backgroundImageUrl}")` : undefined,
+    backgroundSize: 'cover',
+    backgroundPosition: 'center',
+  }}
+>
+  {/* Image element ensures proper loading for waitForPageImages() */}
+  {backgroundImageUrl && !backgroundVideoUrl && (
+    <div className="absolute inset-0 pointer-events-none">
+      {backgroundImageUrl.startsWith('blob:') ? (
+        // Native img for blob URLs - no re-fetch on re-render
+        <img
+          key={backgroundImageUrl}
+          src={backgroundImageUrl}
+          alt=""
+          className="absolute inset-0 w-full h-full object-cover"
+          onLoad={() => setIsBackgroundReady(true)}
+          onError={() => setIsBackgroundReady(true)}
+        />
+      ) : (
+        // Next.js Image for regular URLs - optimization benefits
+        <Image
+          key={backgroundImageUrl}
+          src={backgroundImageUrl}
+          alt=""
+          fill
+          sizes="100vw"
+          className="object-cover"
+          priority
+          unoptimized
+          onLoad={() => setIsBackgroundReady(true)}
+          onError={() => setIsBackgroundReady(true)}
+        />
+      )}
+    </div>
+  )}
+</div>
+```
+
+**Why conditional rendering?**
+- Next.js `<Image>` re-fetches `src` on every re-render, even with `unoptimized`
+- Blob URLs are already in memory - no need for Next.js optimization
+- Native `<img>` is cached by browser and doesn't re-fetch
+- This prevents thousands of unnecessary blob URL requests during animations
+
+**Why both CSS and Image element?**
+- CSS `background-image` provides immediate visual (from browser cache)
+- Image element triggers `onLoad` callback for proper state tracking
+- `waitForPageImages()` uses `img.decode()` which works with both image types
+- This prevents black flash when transitioning between pages
+
+### Background Video
+
+Background videos support configurable playback settings including custom start/end times.
+
+**Video Playback Settings (from `tour_pages`):**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `background_video_autoplay` | BOOLEAN | true | Autoplay on load |
+| `background_video_loop` | BOOLEAN | true | Loop continuously |
+| `background_video_muted` | BOOLEAN | true | Mute audio (required for autoplay) |
+| `background_video_start_time` | DECIMAL(10,1) | null | Start time in seconds |
+| `background_video_end_time` | DECIMAL(10,1) | null | End/loop time in seconds |
+
+**DECIMAL Parsing (Critical):**
+
+Sequelize DECIMAL fields return strings from the database (e.g., `"2.5"` not `2.5`). These must be parsed before use:
+
+```typescript
+// Parse DECIMAL strings for video time settings
+const videoStartTime =
+  selectedPage?.background_video_start_time != null
+    ? parseFloat(String(selectedPage.background_video_start_time))
+    : null;
+const videoEndTime =
+  selectedPage?.background_video_end_time != null
+    ? parseFloat(String(selectedPage.background_video_end_time))
+    : null;
+```
+
+**useBackgroundVideoPlayback Hook:**
+
+The `useBackgroundVideoPlayback` hook handles start/end time control via video events:
+
+```typescript
+const { videoRef: bgVideoRef } = useBackgroundVideoPlayback({
+  videoUrl: backgroundVideoUrl,
+  autoplay: videoAutoplay,
+  loop: videoLoop,
+  muted: videoMuted,
+  startTime: videoStartTime,  // Must be parsed from DECIMAL string
+  endTime: videoEndTime,      // Must be parsed from DECIMAL string
+});
+```
+
+**Note:** When `endTime` is set, native HTML5 `loop` is disabled. The hook handles looping via `timeupdate` event, seeking back to `startTime`.
+
+**Rendering:**
+
+```tsx
+{backgroundVideoUrl && (
+  <video
+    ref={bgVideoRef}
+    key={backgroundVideoUrl}  // Force remount on URL change
+    src={backgroundVideoUrl}
+    autoPlay={videoAutoplay}
+    loop={videoEndTime == null ? videoLoop : false}  // JS handles loop when endTime set
+    muted={videoMuted}
+    playsInline
+    className="absolute inset-0 w-full h-full object-cover"
+  />
+)}
+```
+
+### Background Ready State
+
+For pages without images or with videos, background is immediately ready:
+
+```tsx
+useEffect(() => {
+  if (!selectedPage?.background_image_url || selectedPage?.background_video_url) {
+    setIsBackgroundReady(true);
+  }
+}, [selectedPage?.background_image_url, selectedPage?.background_video_url]);
+```
+
+---
+
+## Preloading Integration
+
+### Extracting Page Links and Elements
+
+Navigation and preload data is extracted from `ui_schema_json` using the shared utility:
+
+```typescript
+import { extractPageLinksAndElements } from '../lib/extractPageLinks';
+
+// Extract page links and preload elements from ui_schema_json
+const { pageLinks, preloadElements } = useMemo(() => {
+  return extractPageLinksAndElements(pages);
+}, [pages]);
+```
+
+This enables:
+1. **pageLinks** - Navigation connections for the neighbor graph
+2. **preloadElements** - Asset URLs (icons, media, transitions) for preloading
+
+Info Panel `target_page` click destinations are extracted from nested `infoPanelSections` as page links. Runtime trigger clicks are ignored when `infoPanelDisabled: true`. When a page renders, every enabled Info Panel element with `infoPanelOpenByDefault: true` opens automatically; missing or false values preserve the legacy closed-by-default behavior. Runtime tracks open Info Panels by element ID, and binds image detail state, fullscreen gallery state, and media-section selected image state to the originating panel ID. Multiple open Info Panels share a single fullscreen backdrop: backdrop clicks close the whole open group, while each panel close button closes only that panel. Runtime clicks from header/title/text sections, span items, and image/card/video/360 items resolve `targetPageSlug` against the current environment's pages; external URL actions open a new browser tab. Cards/media sections support two rendering modes: `mediaOpenMode: 'panel'` opens the item in the side preview panel, and `mediaOpenMode: 'fullscreen'` opens the section's media items in the shared fullscreen `GalleryCarouselOverlay`; video items use `videoUrl` and render with native video controls in both modes. Image detail panels render through a body-level portal so their fullscreen state is not trapped below the canvas stacking context or runtime global controls. When a presentation is already in browser fullscreen, image detail fullscreen uses local expansion and can return to panel view without exiting presentation fullscreen. Embedded presentations first request native panel fullscreen, then same-origin iframe fullscreen, then post `tour-builder:request-fullscreen` to the parent page before falling back to local iframe-viewport fullscreen. Media items with `useAsBackground` replace the current screen background through the same image/video/360 background renderer used by page backgrounds. While the fullscreen gallery overlay is open, runtime top-right controls are not rendered, and 360 iframes in the overlay are not granted iframe fullscreen permission. 360 iframe URLs are normalized through `buildChromeFreeEmbedUrl`; Kuula embeds are rendered with `fs=0` so provider fullscreen controls do not duplicate platform controls while source playback/autorotate parameters are preserved.
+
+### usePreloadOrchestrator
+
+```typescript
+const preloadOrchestrator = usePreloadOrchestrator({
+  pages,
+  pageLinks,                    // From extractPageLinksAndElements
+  elements: preloadElements,    // From extractPageLinksAndElements
+  currentPageId: selectedPageId,
+  pageHistory,
+  enabled: !isLoading && !error,
+  // maxNeighborDepth defaults to 1 - only preload immediate neighbors
+});
+
+// Available methods
+const {
+  isPreloading,
+  preloadedUrls,
+  queueLength,
+  getCachedBlobUrl,       // Async: creates blob URL from cache (by storage key or resolved URL)
+  isUrlPreloaded,
+  getReadyBlobUrl,        // Instant O(1) lookup by storage key: decoded blob URL ready to display
+} = preloadOrchestrator;
+
+// Storage key mapping enables reliable cache lookups
+// regardless of which presigned URL was used for download
+```
+
+### Storage Key Mapping (Key Feature)
+
+The preload system maps assets by **storage key** (canonical path like `assets/project-123/video.mp4`) in addition to download URLs. This enables cache hits even when presigned URLs change.
+
+```typescript
+// Setting transition preview with storage key
+setTransitionPreview({
+  targetPageId,
+  videoUrl: resolveAssetPlaybackUrl(transitionVideoUrl),  // Resolved for playback
+  storageKey: transitionVideoUrl,                         // Raw path for cache lookup
+  isReverse: isBack,
+});
+
+// Lookup priority in useTransitionPlayback:
+// 1. getReadyBlobUrl(storageKey)   → instant O(1) Map lookup (same session)
+// 2. getCachedBlobUrl(storageKey)  → Cache API lookup (~5ms, post-refresh)
+// 3. getReadyBlobUrl(resolvedUrl)  → fallback
+// 4. getCachedBlobUrl(resolvedUrl) → fallback
+// 5. Network fetch                 → last resort
+```
+
+**Why storage key mapping matters:**
+
+| Scenario | Download URL | Storage Key | Lookup Result |
+|----------|-------------|-------------|---------------|
+| Same session | `https://s3...?Sig=ABC` | `assets/vid.mp4` | ✅ Instant via storage key |
+| New presigned URL | `https://s3...?Sig=XYZ` | `assets/vid.mp4` | ✅ Instant via storage key |
+| Page refresh | N/A (in-memory cleared) | `assets/vid.mp4` | ✅ From Cache API by storage key |
+```
+
+### usePageSwitch Integration
+
+The `usePageSwitch` hook provides smooth page transitions using blob URLs from the preload cache:
+
+```typescript
+const pageSwitch = usePageSwitch({
+  preloadCache: preloadOrchestrator
+    ? {
+        getReadyBlobUrl: preloadOrchestrator.getReadyBlobUrl,  // Instant O(1)
+        getCachedBlobUrl: preloadOrchestrator.getCachedBlobUrl,  // Fallback
+        preloadedUrls: preloadOrchestrator.preloadedUrls,
+      }
+    : undefined,
+});
+
+// Switch to a page with smooth background transition
+await pageSwitch.switchToPage(targetPage);
+
+// Canvas background uses resolved blob URLs
+const backgroundImageSrc =
+  pageSwitch.currentBgImageUrl || resolveAssetPlaybackUrl(backgroundImageUrl);
+```
+
+**White Flash Prevention:**
+1. `getReadyBlobUrl()` - O(1) instant lookup for pre-decoded blob URLs
+2. `previousBgImageUrl` - Keeps old background visible during switch
+3. `markBackgroundReady()` - Called when new background loads
+4. `clearPreviousBackground()` - Fades out overlay after paint confirmed
+
+### Preload Priority
+
+```
+Current page assets:    priority = 1000 + assetType weight
+Neighbor (distance 1):  priority = 500 + assetType weight
+
+Asset weights:
+- Transition: +150 (highest - needed immediately on navigation)
+- Image: +100 (backgrounds load during transition playback)
+- Audio: +50
+- Video: +30
+```
+
+**Note:** `maxNeighborDepth` defaults to 1 (immediate neighbors only). Depth 2 was causing too many requests.
+
+### Image Pre-Decode
+
+```typescript
+const waitForPageImages = async (pageId: string) => {
+  const page = pages.find((p) => p.id === pageId);
+  const imageUrls: string[] = [];
+
+  // Collect background image
+  if (page.background_image_url) {
+    imageUrls.push(page.background_image_url);
+  }
+
+  // Collect element images
+  const schema = JSON.parse(page.ui_schema_json || '{}');
+  (schema.elements || []).forEach((el) => {
+    if (el.iconUrl) imageUrls.push(el.iconUrl);
+    if (el.imageUrl) imageUrls.push(el.imageUrl);
+  });
+
+  // Decode all images
+  await Promise.all(
+    imageUrls.map(async (url) => {
+      const img = new Image();
+      img.src = url;
+      try {
+        await Promise.race([
+          img.decode(),
+          new Promise((_, reject) => setTimeout(reject, 2000)),
+        ]);
+      } catch {
+        // Ignore decode failures
+      }
+    })
+  );
+};
+```
+
+---
+
+## Offline Support
+
+### OfflineToggle Component
+
+```tsx
+<OfflineToggle
+  projectId={project.id}
+  projectSlug={projectSlug}
+  projectName={project.name}
+  showLabel={false}
+  size="small"
+/>
+```
+
+### Offline States
+
+| State | UI | Action |
+|-------|-----|--------|
+| `not_downloaded` | "Download for offline" | Click to start |
+| `downloading` | "Downloading 45%" | Progress indicator |
+| `downloaded` | "Available offline" | Checkmark icon |
+| `error` | "Retry download" | Click to retry |
+| `outdated` | "Update available" | Click to update |
+
+### useOfflineMode Hook
+
+```typescript
+const {
+  isOfflineCapable,
+  isDownloaded,
+  isDownloading,
+  status,
+  progress,
+  startDownload,
+  pauseDownload,
+  resumeDownload,
+  cancelDownload,
+  deleteOfflineData,
+  estimatedSize,
+} = useOfflineMode({
+  projectId,
+  projectSlug,
+  projectName,
+});
+```
+
+---
+
+## Fullscreen Mode
+
+### Toggle Fullscreen
+
+```typescript
+const [isFullscreen, setIsFullscreen] = useState(false);
+
+const toggleFullscreen = useCallback(async () => {
+  if (!document.fullscreenElement) {
+    await document.documentElement.requestFullscreen();
+    setIsFullscreen(true);
+  } else {
+    await document.exitFullscreen();
+    setIsFullscreen(false);
+  }
+}, []);
+
+// Listen for ESC key exit
+useEffect(() => {
+  const handleFullscreenChange = () => {
+    setIsFullscreen(Boolean(document.fullscreenElement));
+  };
+  document.addEventListener('fullscreenchange', handleFullscreenChange);
+  return () => document.removeEventListener('fullscreenchange', handleFullscreenChange);
+}, []);
+```
+
+### Fullscreen Button
+
+```tsx
+<button
+  onClick={toggleFullscreen}
+  className="absolute top-4 right-16 z-40"
+>
+  {isFullscreen ? <ExitFullscreenIcon /> : <FullscreenIcon />}
+</button>
+```
+
+---
+
+## Head Meta Tags
+
+The component renders SEO and social sharing meta tags in the `<Head>` component:
+
+```tsx
+<Head>
+  <title>{project?.name || 'Presentation'}</title>
+  {faviconUrl && <link key="favicon" rel="icon" href={faviconUrl} />}
+  {ogImageUrl && (
+    <>
+      <meta key="og:image" property="og:image" content={ogImageUrl} />
+      <meta key="twitter:image:src" property="twitter:image:src" content={ogImageUrl} />
+    </>
+  )}
+  {project?.name && (
+    <>
+      <meta key="og:title" property="og:title" content={project.name} />
+      <meta key="twitter:title" property="twitter:title" content={project.name} />
+    </>
+  )}
+  {project?.description && (
+    <>
+      <meta key="og:description" property="og:description" content={project.description} />
+      <meta key="twitter:description" property="twitter:description" content={project.description} />
+    </>
+  )}
+</Head>
+```
+
+**Meta tags rendered:**
+- **favicon** - Project favicon via presigned URL from `useProjectAssets`
+- **og:image / twitter:image:src** - Open Graph image for social sharing
+- **og:title / twitter:title** - Project name for social sharing
+- **og:description / twitter:description** - Project description for social sharing
+
+---
+
+## Gallery Carousel Overlay
+
+When users click on gallery cards, a fullscreen carousel overlay opens for navigating through images.
+
+### State Management
+
+```typescript
+const [activeGalleryCarousel, setActiveGalleryCarousel] = useState<{
+  element: any;
+  initialIndex: number;
+} | null>(null);
+```
+
+### Gallery Card Click Handler
+
+```typescript
+const handleGalleryCardClick = useCallback(
+  (element: any, cardIndex: number) => {
+    if (element.galleryCards?.length > 0) {
+      setActiveGalleryCarousel({ element, initialIndex: cardIndex });
+    }
+  },
+  [],
+);
+```
+
+### GalleryCarouselOverlay Component
+
+The overlay provides:
+- Fullscreen image carousel with swipe navigation
+- Customizable prev/next/back button icons and positions
+- Percentage-based button positioning (like canvas elements)
+- Draggable buttons in constructor edit mode
+- No runtime chrome controls while open: download, fullscreen, and global mute
+  buttons are hidden. Gallery videos still read the global muted state.
+
+Info Panel image detail fullscreen is separate from `GalleryCarouselOverlay`.
+It is portaled to `document.body` and uses z-index values above
+`RuntimeControls` so detail fullscreen controls remain clickable while global
+presentation controls stay behind the image view.
+
+```tsx
+{activeGalleryCarousel && (
+  <GalleryCarouselOverlay
+    cards={activeGalleryCarousel.element.galleryCards || []}
+    initialIndex={activeGalleryCarousel.initialIndex}
+    onClose={() => setActiveGalleryCarousel(null)}
+    resolveUrl={resolveUrlWithBlob}
+    prevIconUrl={activeGalleryCarousel.element.galleryCarouselPrevIconUrl}
+    nextIconUrl={activeGalleryCarousel.element.galleryCarouselNextIconUrl}
+    backIconUrl={activeGalleryCarousel.element.galleryCarouselBackIconUrl}
+    backLabel={activeGalleryCarousel.element.galleryCarouselBackLabel || 'BACK'}
+    prevX={activeGalleryCarousel.element.galleryCarouselPrevX}
+    prevY={activeGalleryCarousel.element.galleryCarouselPrevY}
+    nextX={activeGalleryCarousel.element.galleryCarouselNextX}
+    nextY={activeGalleryCarousel.element.galleryCarouselNextY}
+    backX={activeGalleryCarousel.element.galleryCarouselBackX}
+    backY={activeGalleryCarousel.element.galleryCarouselBackY}
+    isEditMode={false}
+  />
+)}
+```
+
+---
+
+## Mobile/Touch Support
+
+### Touch-Friendly Elements
+
+- Large touch targets for navigation buttons
+- `playsInline` attribute on videos for iOS
+- Responsive sizing with `w-full h-full object-cover`
+- Standard click handlers work for touch events
+
+### Video Autoplay Policies
+
+```tsx
+<video
+  autoPlay
+  muted        // Required for autoplay on mobile
+  playsInline  // Required for inline playback on iOS
+  loop
+/>
+```
+
+---
+
+## Comparison: Runtime vs Constructor
+
+| Aspect | Runtime | Constructor |
+|--------|---------|-------------|
+| **Purpose** | View presentations | Edit content |
+| **Access** | Public or authenticated | Authenticated only |
+| **Environment** | `stage` or `production` | `dev` only |
+| **Full-screen** | Yes | No |
+| **Transitions** | Play forward/reverse | Preview only |
+| **Offline Support** | Full caching | Not supported |
+| **Preloading** | Neighbor graph (depth 1) | Same (depth 1) |
+| **Element Interaction** | Click-to-navigate | Drag-to-edit |
+| **Background Video** | Looping auto-play | Static display |
+| **UI Schema Source** | `ui_schema_json` | `ui_schema_json` + live edits |
+
+---
+
+## Key Files Reference
+
+### Hooks
+
+| File | Purpose |
+|------|---------|
+| `hooks/usePageDataLoader.ts` | Project and page data loading (shared with constructor) |
+| `hooks/useProjectAssets.ts` | Resolves project assets (favicon, og_image, logo) to presigned URLs |
+| `hooks/usePreloadOrchestrator.ts` | Asset preload with blob URL caching (S3 direct → Cache API → blob URLs) |
+| `hooks/usePageSwitch.ts` | Smooth page transitions with preload integration |
+| `hooks/useTransitionPlayback.ts` | Transition video playback (forward + reverse) |
+| `hooks/useBackgroundTransition.ts` | Background fade-out animation coordination |
+| `hooks/useBackgroundVideoPlayback.ts` | Background video time control (start/end time) |
+| `hooks/useReversePlayback.ts` | Low-level reverse video playback |
+| `hooks/useNeighborGraph.ts` | Navigation graph building from pageLinks |
+| `hooks/useOfflineMode.ts` | Offline download management |
+
+### Components
+
+| File | Purpose |
+|------|---------|
+| `components/RuntimePresentation.tsx` | Main presentation component |
+| `components/RuntimeElement.tsx` | Element wrapper with positioning and effects |
+| `components/UiElements/UiElementRenderer.tsx` | Unified element rendering (WYSIWYG consistency) |
+| `components/UiElements/GalleryCarouselOverlay.tsx` | Fullscreen gallery carousel overlay |
+| `components/UiElements/shared/useElementWrapperStyle.ts` | Shared styling hook for consistent wrapper styling |
+| `components/UiElements/elements/*.tsx` | Per-type element components (NavigationElement, GalleryElement, etc.) |
+| `components/Offline/OfflineToggle.tsx` | Offline toggle button |
+
+### Pages
+
+| File | Purpose |
+|------|---------|
+| `pages/runtime.tsx` | Admin runtime viewer |
+| `pages/p/[projectSlug]/index.tsx` | Production presentation |
+| `pages/p/[projectSlug]/stage.tsx` | Stage presentation |
+
+### Libraries & Helpers
+
+| File | Purpose |
+|------|---------|
+| `lib/extractPageLinks.ts` | Extract pageLinks and preloadElements from ui_schema_json |
+| `lib/navigationHelpers.ts` | Navigation utilities: resolveNavigationTarget, isTransitionBlocking |
+| `lib/assetUrl.ts` | Asset URL resolution (resolveAssetPlaybackUrl) |
+| `lib/logger.ts` | Structured logging |
+
+### Configuration & Types
+
+| File | Purpose |
+|------|---------|
+| `config/preload.config.ts` | Preload settings: priority weights, maxDepth, asset field names |
+| `types/runtime.ts` | Runtime type definitions |
+| `types/preload.ts` | Preload type definitions (PreloadPageLink, PreloadElement, etc.) |
+| `types/presentation.ts` | TransitionPhase type |
+
+### Backend Files
+
+| File | Purpose |
+|------|---------|
+| `routes/runtime-context.ts` | Context detection endpoint |
+| `middlewares/runtime-context.ts` | Context detection middleware |
+| `middlewares/runtime-public.ts` | Public field filtering |
+
+---
+
+## Configuration
+
+### Preload Configuration
+
+```typescript
+// config/preload.config.ts
+{
+  maxConcurrentDownloads: 3,
+  neighborGraph: {
+    maxDepth: 1,  // Only preload immediate neighbors
+  },
+  priority: {
+    currentPage: 1000,
+    neighborBase: 500,
+    assetType: {
+      transition: 150,  // Highest - needed immediately on navigation
+      image: 100,       // Backgrounds load during transition playback
+      audio: 50,
+      video: 30,
+    },
+  },
+  assetFields: {
+    // Asset URL fields extracted from ui_schema_json
+    all: ['iconUrl', 'imageUrl', 'mediaUrl', 'transitionVideoUrl', ...],
+    nested: ['galleryCards', 'carouselSlides'],
+  },
+}
+```
+
+### Offline Configuration
+
+```typescript
+// config/offline.config.ts
+{
+  cacheNames: {
+    assets: 'tour-builder-assets-v1',
+  },
+  storage: {
+    indexedDbMinSize: 5 * 1024 * 1024,  // 5MB
+    warningPercent: 80,
+    criticalPercent: 95,
+  },
+}
+```
+
+---
+
+## Performance Optimizations
+
+1. **Storage Key Mapping** - Assets cached by canonical storage path (e.g., `assets/vid.mp4`), enabling cache hits regardless of presigned URL signature changes
+2. **Instant Blob URL Lookup** - `getReadyBlobUrl(storageKey)` provides O(1) lookup for pre-decoded blob URLs ready to display
+3. **Image Pre-Decode During Playback** - Decode images DURING transition video playback (not after) to eliminate black flash
+4. **Double RAF Paint Sync** - Two `requestAnimationFrame` calls ensure new page is painted before overlay removal
+5. **Priority Preloading** - Current page assets load first, then immediate neighbors (depth 1)
+6. **S3 Direct Download** - Assets downloaded directly from S3 presigned URLs, cached in browser Cache API
+7. **Concurrent Downloads** - 3 parallel downloads maximize throughput
+8. **Network-Aware** - Adaptive concurrency based on connection speed
+9. **Hybrid Storage** - Cache API for small files (<5MB), IndexedDB for large videos (≥5MB)
+10. **Cached Video Seeking** - Blob URLs from cache enable smooth reverse playback
+11. **Neighbor Graph** - BFS traversal finds reachable pages (1 hop to reduce requests)
+12. **Instant Video Overlay** - Container hidden while buffering, instant removal when bg ready (no fade)
+13. **Smooth Crossfade** - 700ms CSS animation with Material Design easing for non-video navigation
+14. **usePageSwitch** - Keeps previous background visible until new one is painted
+14. **Post-Refresh Cache** - Assets stored in Cache API under storage key survive page refresh
+
+---
+
+## Troubleshooting
+
+### Page Not Loading
+1. Check runtime context detection
+2. Verify project slug matches
+3. Check X-Runtime-* headers sent
+4. Verify environment filtering
+
+### Transitions Not Playing
+1. Check transition video URL valid
+2. Verify supports_reverse for back navigation
+3. Check useTransitionPlayback errors in console
+4. Verify video preloaded via preloadOrchestrator
+5. Check isBuffering state in overlay rendering
+
+### Offline Mode Issues
+1. Check Service Worker registered
+2. Verify storage quota available
+3. Check IndexedDB for cached assets
+4. Test with DevTools offline mode
+
+### Black Flash on Navigation (Fixed)
+
+**Problem:** Black flashes appeared during page transitions at three points:
+1. **At transition START** - Video not ready when overlay appears
+2. **At transition END** - Background not ready when overlay removed
+3. **On direct navigation** - No transition video to cover the switch
+
+**Root Causes:**
+- `isBuffering` only tracked reverse playback, not initial video loading
+- CSS `background-image` vs `img.decode()` mismatch - decode worked on Image elements but background used CSS
+- Overlay removed before new page fully painted
+
+**Solution - 5-Phase Implementation:**
+
+| Phase | Fix | Implementation |
+|-------|-----|----------------|
+| 1 | Use `phase` for overlay opacity | `opacity: transitionPhase === 'preparing' \|\| isBuffering ? 0 : 1` |
+| 2 | Add Image element for background | Next.js `<Image>` with `onLoad={() => setIsBackgroundReady(true)}` |
+| 3 | Keep transition frame until ready | `pendingTransitionComplete && isBackgroundReady` guards overlay removal |
+| 4 | Fix direct navigation | `setIsBackgroundReady(false)` before page change |
+| 5 | Video cleanup | `video.removeAttribute('src'); video.load()` prevents memory leaks |
+
+**Timing Sequence:**
+```
+Navigation WITH transition:
+1. User clicks → setTransitionPreview() → overlay renders (opacity: 0)
+2. Video loads → phase: 'preparing' → 'playing' → overlay fades in
+3. Video ends → onComplete fires → waitForPageImages() → page switches
+4. Image onLoad → isBackgroundReady: true
+5. Effect triggers → RAF × 2 → overlay removed
+
+Navigation WITHOUT transition:
+1. User clicks → waitForPageImages() → setIsBackgroundReady(false)
+2. Page switches → Image onLoad → isBackgroundReady: true
+3. New page visible immediately (no overlay needed)
+```
+
+**Key Files:**
+- `RuntimePresentation.tsx:132` - Phase destructuring from useTransitionPlayback
+- `RuntimePresentation.tsx:179-190` - useBackgroundTransition hook for fade-out effects
+- `RuntimePresentation.tsx:444-483` - Background Image element with onLoad
diff --git a/frontend/docs/schemas-module.md b/frontend/docs/schemas-module.md
new file mode 100644
index 0000000..55225cc
--- /dev/null
+++ b/frontend/docs/schemas-module.md
@@ -0,0 +1,631 @@
+# Frontend Schemas Module
+
+## Overview
+
+The Schemas module provides **Zod validation schemas** for form validation across the frontend application. These schemas define data validation rules, generate TypeScript types, and provide initial form values for entity forms.
+
+**Location:** `frontend/src/schemas/`
+
+**Total Files:** 6 files (~257 LOC)
+
+**Library:** [Zod](https://zod.dev/) - TypeScript-first schema validation
+
+---
+
+## Architecture
+
+```
+frontend/src/schemas/
+├── index.ts           (9 LOC)    # Central exports
+├── userSchema.ts      (80 LOC)   # User validation (create/update)
+├── assetSchema.ts     (85 LOC)   # Asset validation
+├── projectSchema.ts   (31 LOC)   # Project validation
+├── tourPageSchema.ts  (35 LOC)   # Tour page validation
+└── roleSchema.ts      (17 LOC)   # Role validation
+```
+
+**Related Schema:** `frontend/src/lib/offlineDb/schema.ts` - Dexie IndexedDB schema (separate concern)
+
+---
+
+## Schema Pattern
+
+Each schema file follows a consistent pattern:
+
+```typescript
+/**
+ * 1. Zod schema definition
+ */
+export const entitySchema = z.object({
+  fieldName: z.string().min(1, 'Error message'),
+  // ...
+});
+
+/**
+ * 2. TypeScript type inference
+ */
+export type EntityFormData = z.infer<typeof entitySchema>;
+
+/**
+ * 3. Initial form values
+ */
+export const entityInitialValues: EntityFormData = {
+  fieldName: '',
+  // ...
+};
+```
+
+---
+
+## Schema Files
+
+### 1. User Schema (`userSchema.ts`)
+
+**Purpose:** Validation for user creation and update forms.
+
+**Lines:** 80 LOC
+
+#### Schemas
+
+```typescript
+// User creation - requires email, optional password
+export const userCreateSchema = z.object({
+  firstName: z.string().max(255, 'First name too long').optional().or(z.literal('')),
+  lastName: z.string().max(255, 'Last name too long').optional().or(z.literal('')),
+  phoneNumber: z.string().max(50, 'Phone number too long').optional().or(z.literal('')),
+  email: z.string().email('Invalid email address').min(1, 'Email is required'),
+  password: z.string().min(6, 'Password must be at least 6 characters').optional().or(z.literal('')),
+  disabled: z.boolean().default(false),
+  avatar: z.array(z.unknown()).optional(),
+  app_role: z.unknown().optional().nullable(),
+  custom_permissions: z.array(z.unknown()).optional(),
+});
+
+// User update - same fields, password optional
+export const userUpdateSchema = z.object({
+  // Same structure as userCreateSchema
+});
+```
+
+#### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `userCreateSchema` | ZodObject | Create user validation |
+| `userUpdateSchema` | ZodObject | Update user validation |
+| `UserCreateFormData` | Type | Inferred create form type |
+| `UserUpdateFormData` | Type | Inferred update form type |
+| `userInitialValues` | Object | Default form values |
+
+#### Field Validations
+
+| Field | Validation | Error Message |
+|-------|------------|---------------|
+| `firstName` | max(255), optional | "First name too long" |
+| `lastName` | max(255), optional | "Last name too long" |
+| `phoneNumber` | max(50), optional | "Phone number too long" |
+| `email` | email(), min(1) | "Invalid email address", "Email is required" |
+| `password` | min(6), optional | "Password must be at least 6 characters" |
+| `disabled` | boolean, default(false) | - |
+| `avatar` | array, optional | - |
+| `app_role` | unknown, optional, nullable | - |
+| `custom_permissions` | array, optional | - |
+
+---
+
+### 2. Asset Schema (`assetSchema.ts`)
+
+**Purpose:** Validation for asset upload and edit forms.
+
+**Lines:** 85 LOC
+
+#### Schema
+
+```typescript
+export const assetSchema = z.object({
+  project: z.unknown().optional().nullable(),
+  name: z.string().min(1, 'Name is required').max(255, 'Name too long'),
+  asset_type: z.enum(['image', 'video', 'audio', 'file']),
+  type: z.enum([
+    'general', 'icon', 'background_image', 'audio',
+    'video', 'transition', 'logo', 'favicon', 'document',
+  ]).default('general'),
+  cdn_url: z.string().url('Invalid URL').optional().or(z.literal('')),
+  storage_key: z.string().max(500, 'Storage key too long').optional().or(z.literal('')),
+  mime_type: z.string().max(100, 'MIME type too long').optional().or(z.literal('')),
+  size_mb: z.coerce.number().min(0, 'Size cannot be negative').optional().or(z.literal('')),
+  width_px: z.coerce.number().int().min(0, 'Width cannot be negative').optional().or(z.literal('')),
+  height_px: z.coerce.number().int().min(0, 'Height cannot be negative').optional().or(z.literal('')),
+  duration_sec: z.coerce.number().min(0, 'Duration cannot be negative').optional().or(z.literal('')),
+  checksum: z.string().max(255, 'Checksum too long').optional().or(z.literal('')),
+  is_public: z.boolean().default(false),
+  is_deleted: z.boolean().default(false),
+  deleted_at_time: z.date().optional().nullable(),
+});
+```
+
+#### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `assetSchema` | ZodObject | Asset validation schema |
+| `AssetFormData` | Type | Inferred form type |
+| `assetInitialValues` | Object | Default form values |
+
+#### Enum Values
+
+**asset_type:**
+- `image` - Image files (PNG, JPG, WebP, etc.)
+- `video` - Video files (MP4, WebM, etc.)
+- `audio` - Audio files (MP3, WAV, etc.)
+- `file` - Generic files (documents, etc.)
+
+**type (usage category):**
+- `general` - Default category
+- `icon` - UI icons
+- `background_image` - Page backgrounds
+- `audio` - Background audio
+- `video` - Video content
+- `transition` - Transition videos
+- `logo` - Brand logos
+- `favicon` - Site favicons
+- `document` - Documents/PDFs
+
+#### Coercion Pattern
+
+Number fields use `z.coerce` for form input handling:
+
+```typescript
+// Converts string input to number, validates, allows empty string
+size_mb: z.coerce
+  .number()
+  .min(0, 'Size cannot be negative')
+  .optional()
+  .or(z.literal(''))
+```
+
+---
+
+### 3. Project Schema (`projectSchema.ts`)
+
+**Purpose:** Validation for project creation and edit forms.
+
+**Lines:** 31 LOC
+
+#### Schema
+
+```typescript
+export const projectSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(255, 'Name too long'),
+  slug: z.string()
+    .max(255, 'Slug too long')
+    .regex(
+      /^[a-z0-9_-]*$/i,
+      'Slug can only contain letters, numbers, dashes, underscores',
+    )
+    .optional()
+    .or(z.literal('')),
+  description: z.string().max(5000, 'Description too long').optional().or(z.literal('')),
+});
+```
+
+#### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `projectSchema` | ZodObject | Project validation schema |
+| `ProjectFormData` | Type | Inferred form type |
+| `projectInitialValues` | Object | Default form values |
+
+#### Slug Validation
+
+The slug field uses regex validation for URL-safe strings:
+
+```typescript
+.regex(/^[a-z0-9_-]*$/i, 'Slug can only contain letters, numbers, dashes, underscores')
+```
+
+**Valid:** `my-project`, `project_123`, `MyProject`
+**Invalid:** `my project`, `project@123`, `project/name`
+
+---
+
+### 4. Tour Page Schema (`tourPageSchema.ts`)
+
+**Purpose:** Validation for tour page creation and edit forms.
+
+**Lines:** 35 LOC
+
+#### Schema
+
+```typescript
+export const tourPageSchema = z.object({
+  project: z.unknown().optional().nullable(),
+  title: z.string().max(255, 'Title too long').optional().or(z.literal('')),
+  slug: z.string()
+    .max(255, 'Slug too long')
+    .regex(
+      /^[a-z0-9_-]*$/i,
+      'Slug can only contain letters, numbers, dashes, underscores',
+    )
+    .optional()
+    .or(z.literal('')),
+  background_asset: z.unknown().optional().nullable(),
+  audio_asset: z.unknown().optional().nullable(),
+  is_start_page: z.boolean().default(false),
+  sort_order: z.coerce.number().int().min(0).optional().or(z.literal('')),
+});
+```
+
+#### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `tourPageSchema` | ZodObject | Tour page validation schema |
+| `TourPageFormData` | Type | Inferred form type |
+| `tourPageInitialValues` | Object | Default form values |
+
+#### Initial Values
+
+```typescript
+export const tourPageInitialValues: TourPageFormData = {
+  project: null,
+  title: '',
+  slug: '',
+  background_asset: null,
+  audio_asset: null,
+  is_start_page: false,
+  sort_order: '',
+};
+```
+
+---
+
+### 5. Role Schema (`roleSchema.ts`)
+
+**Purpose:** Validation for role creation and edit forms.
+
+**Lines:** 17 LOC
+
+#### Schema
+
+```typescript
+export const roleSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(255, 'Name too long'),
+  permissions: z.array(z.unknown()).optional(),
+});
+```
+
+#### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `roleSchema` | ZodObject | Role validation schema |
+| `RoleFormData` | Type | Inferred form type |
+| `roleInitialValues` | Object | Default form values |
+
+#### Initial Values
+
+```typescript
+export const roleInitialValues: RoleFormData = {
+  name: '',
+  permissions: [],
+};
+```
+
+---
+
+### 6. Index File (`index.ts`)
+
+**Purpose:** Central re-export for all schemas.
+
+**Lines:** 9 LOC
+
+```typescript
+export * from './userSchema';
+export * from './projectSchema';
+export * from './assetSchema';
+export * from './roleSchema';
+export * from './tourPageSchema';
+```
+
+---
+
+## Zod Validation Patterns
+
+### 1. Optional with Empty String
+
+Allow field to be empty or have valid value:
+
+```typescript
+// Accepts: undefined, '', or valid string
+fieldName: z.string().optional().or(z.literal(''))
+```
+
+### 2. Required String
+
+Field must have non-empty value:
+
+```typescript
+// Fails on empty string
+name: z.string().min(1, 'Name is required')
+```
+
+### 3. Email Validation
+
+Built-in email format validation:
+
+```typescript
+email: z.string().email('Invalid email address').min(1, 'Email is required')
+```
+
+### 4. Enum Validation
+
+Restrict to specific values:
+
+```typescript
+asset_type: z.enum(['image', 'video', 'audio', 'file'])
+```
+
+### 5. Number Coercion
+
+Convert string input to number:
+
+```typescript
+// Input: "123" → number 123
+// Input: "" → literal ''
+size_mb: z.coerce.number().min(0).optional().or(z.literal(''))
+```
+
+### 6. Regex Pattern
+
+Validate string format:
+
+```typescript
+slug: z.string().regex(/^[a-z0-9_-]*$/i, 'Error message')
+```
+
+### 7. Nullable Relation
+
+Optional reference to another entity:
+
+```typescript
+project: z.unknown().optional().nullable()
+```
+
+### 8. Boolean with Default
+
+Boolean field with default value:
+
+```typescript
+disabled: z.boolean().default(false)
+```
+
+---
+
+## Type Inference
+
+Zod schemas generate TypeScript types automatically:
+
+```typescript
+// Define schema
+const projectSchema = z.object({
+  name: z.string().min(1),
+  slug: z.string().optional(),
+});
+
+// Infer type
+type ProjectFormData = z.infer<typeof projectSchema>;
+
+// Equivalent to:
+// type ProjectFormData = {
+//   name: string;
+//   slug?: string;
+// }
+```
+
+---
+
+## Usage with Formik
+
+Schemas can be integrated with Formik using adapters:
+
+### Option 1: Manual Validation
+
+```typescript
+import { projectSchema, projectInitialValues } from '@/schemas';
+
+const validate = (values) => {
+  const result = projectSchema.safeParse(values);
+  if (!result.success) {
+    const errors = {};
+    result.error.issues.forEach((issue) => {
+      errors[issue.path[0]] = issue.message;
+    });
+    return errors;
+  }
+  return {};
+};
+
+<Formik
+  initialValues={projectInitialValues}
+  validate={validate}
+  onSubmit={handleSubmit}
+>
+  {/* form fields */}
+</Formik>
+```
+
+### Option 2: Zod-Formik Adapter
+
+```typescript
+import { toFormikValidationSchema } from 'zod-formik-adapter';
+import { projectSchema, projectInitialValues } from '@/schemas';
+
+<Formik
+  initialValues={projectInitialValues}
+  validationSchema={toFormikValidationSchema(projectSchema)}
+  onSubmit={handleSubmit}
+>
+  {/* form fields */}
+</Formik>
+```
+
+---
+
+## Related: IndexedDB Schema
+
+The `lib/offlineDb/schema.ts` file defines the **Dexie.js** IndexedDB schema for offline storage (separate from form validation):
+
+```typescript
+class OfflineDatabase extends Dexie {
+  assets!: EntityTable<OfflineAsset, 'id'>;
+  projects!: EntityTable<OfflineProject, 'id'>;
+  downloadQueue!: EntityTable<DownloadQueueItem, 'id'>;
+
+  constructor() {
+    super(OFFLINE_CONFIG.dbName);
+
+    this.version(OFFLINE_CONFIG.dbVersion).stores({
+      assets: 'id, projectId, url, variantType, assetType, downloadedAt',
+      projects: 'id, slug, status, lastSyncedAt',
+      downloadQueue: 'id, projectId, status, priority, addedAt',
+    });
+  }
+}
+
+export const offlineDb = new OfflineDatabase();
+```
+
+**Key Differences:**
+
+| Aspect | Zod Schemas | Dexie Schema |
+|--------|-------------|--------------|
+| Purpose | Form validation | Database structure |
+| Library | Zod | Dexie.js |
+| Location | `schemas/` | `lib/offlineDb/` |
+| Runtime | Client-side validation | IndexedDB storage |
+
+---
+
+## Schema Inventory
+
+| File | LOC | Entity | Fields | Exports |
+|------|-----|--------|--------|---------|
+| `userSchema.ts` | 80 | User | 9 fields | 5 (2 schemas, 2 types, 1 initial) |
+| `assetSchema.ts` | 85 | Asset | 14 fields | 3 (1 schema, 1 type, 1 initial) |
+| `tourPageSchema.ts` | 35 | TourPage | 7 fields | 3 (1 schema, 1 type, 1 initial) |
+| `projectSchema.ts` | 31 | Project | 3 fields | 3 (1 schema, 1 type, 1 initial) |
+| `roleSchema.ts` | 17 | Role | 2 fields | 3 (1 schema, 1 type, 1 initial) |
+| `index.ts` | 9 | - | - | Re-exports all |
+| **Total** | **257** | **5** | **35** | **17** |
+
+---
+
+## Best Practices
+
+### 1. Consistent Error Messages
+
+Use descriptive, user-friendly error messages:
+
+```typescript
+// Good
+name: z.string().min(1, 'Name is required').max(255, 'Name too long')
+
+// Avoid
+name: z.string().min(1).max(255)  // Generic messages
+```
+
+### 2. Type-Safe Initial Values
+
+Use inferred type for initial values:
+
+```typescript
+export const projectInitialValues: ProjectFormData = {
+  name: '',      // TypeScript enforces this matches schema
+  slug: '',
+  description: '',
+};
+```
+
+### 3. Empty String Handling
+
+For optional fields that may receive empty strings from forms:
+
+```typescript
+// Allows both undefined and empty string
+fieldName: z.string().optional().or(z.literal(''))
+```
+
+### 4. Relation Fields
+
+Use `z.unknown()` for relation fields that hold entity references:
+
+```typescript
+// Accepts any value - actual validation happens on backend
+project: z.unknown().optional().nullable()
+```
+
+### 5. Number Input Handling
+
+Use `z.coerce` for number fields from text inputs:
+
+```typescript
+// Converts "123" to 123, validates as number
+amount: z.coerce.number().min(0)
+```
+
+---
+
+## Related Documentation
+
+- [types-module.md](./types-module.md) - Entity type definitions
+- [factories-module.md](./factories-module.md) - Form page factory (uses schemas)
+- [lib-module.md](./lib-module.md) - Offline storage schema
+- [hooks-module.md](./hooks-module.md) - Form hooks
+
+---
+
+## Adding New Schemas
+
+To add validation for a new entity:
+
+### Step 1: Create Schema File
+
+```typescript
+// schemas/widgetSchema.ts
+import { z } from 'zod';
+
+export const widgetSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(255, 'Name too long'),
+  type: z.enum(['basic', 'advanced']).default('basic'),
+  config: z.record(z.unknown()).optional(),
+});
+
+export type WidgetFormData = z.infer<typeof widgetSchema>;
+
+export const widgetInitialValues: WidgetFormData = {
+  name: '',
+  type: 'basic',
+  config: {},
+};
+```
+
+### Step 2: Export from Index
+
+```typescript
+// schemas/index.ts
+export * from './widgetSchema';
+```
+
+### Step 3: Use in Form
+
+```typescript
+import { widgetSchema, widgetInitialValues, type WidgetFormData } from '@/schemas';
+
+// With validation
+const validate = (values: WidgetFormData) => {
+  const result = widgetSchema.safeParse(values);
+  // ... handle errors
+};
+```
diff --git a/frontend/docs/stores-module.md b/frontend/docs/stores-module.md
new file mode 100644
index 0000000..a5a36ae
--- /dev/null
+++ b/frontend/docs/stores-module.md
@@ -0,0 +1,1044 @@
+# Frontend Stores Module
+
+## Overview
+
+The Stores module implements **Redux Toolkit** state management for the frontend application. It provides a centralized store with core UI/auth slices, entity CRUD slices, and runtime-setting slices for transition and global UI-control defaults.
+
+**Location:** `frontend/src/stores/`
+
+**Total Files:** 26+ TypeScript files
+
+**Key Technologies:**
+- Redux Toolkit 2.1.0
+- Axios for API calls
+- JWT for token handling
+
+---
+
+## Architecture
+
+```
+frontend/src/stores/
+├── store.ts                    # Main Redux store configuration (~49 LOC)
+├── hooks.ts                    # Typed hooks (useAppDispatch, useAppSelector) (~6 LOC)
+├── createEntitySlice.ts        # Entity slice factory (~337 LOC)
+├── selectors.ts                # Memoized selectors (~181 LOC)
+│
+├── Core Slices (4)
+│   ├── authSlice.ts            # Authentication state (~123 LOC)
+│   ├── styleSlice.ts           # UI styling/theming (~107 LOC)
+│   ├── mainSlice.ts            # Main app state (~32 LOC)
+│
+├── Entity/Runtime Setting Slices
+│   ├── users/usersSlice.ts         # (~25 LOC)
+│   ├── roles/rolesSlice.ts         # (~96 LOC)
+│   ├── permissions/permissionsSlice.ts  # (~25 LOC)
+│   ├── projects/projectsSlice.ts   # (~25 LOC)
+│   ├── project_memberships/project_membershipsSlice.ts  # (~25 LOC)
+│   ├── assets/assetsSlice.ts       # (~26 LOC)
+│   ├── asset_variants/asset_variantsSlice.ts  # (~25 LOC)
+│   ├── presigned_url_requests/presigned_url_requestsSlice.ts  # (~25 LOC)
+│   ├── tour_pages/tour_pagesSlice.ts  # (~25 LOC)
+│   ├── project_audio_tracks/project_audio_tracksSlice.ts  # (~25 LOC)
+│   ├── publish_events/publish_eventsSlice.ts  # (~25 LOC)
+│   ├── pwa_caches/pwa_cachesSlice.ts  # (~25 LOC)
+│   ├── access_logs/access_logsSlice.ts  # (~25 LOC)
+│   ├── global_transition_defaults/globalTransitionDefaultsSlice.ts  # Public GET (~138 LOC)
+│   ├── project_transition_settings/projectTransitionSettingsSlice.ts  # Public prod GET (~275 LOC)
+│   ├── global_ui_control_defaults/globalUiControlDefaultsSlice.ts  # Public GET singleton defaults
+│   ├── project_ui_control_settings/projectUiControlSettingsSlice.ts  # Project/env UI-control overrides
+│   └── constructor/constructorSlice.ts  # Constructor state (~110 LOC)
+│
+├── Data Files
+│   └── introSteps.ts           # Onboarding tour definitions (~122 LOC)
+│
+└── Legacy (deprecated)
+    └── usersSlice.ts           # Old users slice (use users/usersSlice.ts)
+```
+
+---
+
+## Store Configuration
+
+**File:** `store.ts`
+
+The main store combines all slice reducers:
+
+```typescript
+import { configureStore } from '@reduxjs/toolkit';
+
+export const store = configureStore({
+  reducer: {
+    // Core slices
+    style: styleReducer,
+    main: mainReducer,
+    auth: authSlice,
+
+    // Entity and runtime-setting slices
+    users: usersSlice,
+    roles: rolesSlice,
+    permissions: permissionsSlice,
+    projects: projectsSlice,
+    project_memberships: project_membershipsSlice,
+    assets: assetsSlice,
+    asset_variants: asset_variantsSlice,
+    presigned_url_requests: presigned_url_requestsSlice,
+    tour_pages: tour_pagesSlice,
+    project_audio_tracks: project_audio_tracksSlice,
+    publish_events: publish_eventsSlice,
+    pwa_caches: pwa_cachesSlice,
+    access_logs: access_logsSlice,
+    global_transition_defaults: globalTransitionDefaultsSlice,
+    project_transition_settings: projectTransitionSettingsSlice,
+    global_ui_control_defaults: globalUiControlDefaultsSlice,
+    project_ui_control_settings: projectUiControlSettingsSlice,
+  },
+});
+
+// Inferred types for type safety
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+```
+
+---
+
+## Typed Hooks
+
+**File:** `hooks.ts`
+
+```typescript
+import { TypedUseSelectorHook, useDispatch, useSelector } from 'react-redux';
+import type { RootState, AppDispatch } from './store';
+
+// Use throughout app instead of plain useDispatch and useSelector
+export const useAppDispatch: () => AppDispatch = useDispatch;
+export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;
+```
+
+**Usage:**
+```typescript
+import { useAppDispatch, useAppSelector } from '../stores/hooks';
+
+const MyComponent = () => {
+  const dispatch = useAppDispatch();
+  const users = useAppSelector((state) => state.users.users);
+  const loading = useAppSelector((state) => state.users.loading);
+
+  // Dispatch actions with full type inference
+  dispatch(fetch({ query: '?limit=100' }));
+};
+```
+
+---
+
+## Entity Slice Factory
+
+**File:** `createEntitySlice.ts` (~342 LOC)
+
+The factory generates Redux slices with standard CRUD operations for any entity.
+
+### Configuration Interface
+
+```typescript
+interface EntitySliceConfig {
+  name: string;          // Slice name (e.g., 'users')
+  endpoint: string;      // API endpoint (e.g., 'users')
+  singularName?: string; // For notifications (e.g., 'User')
+}
+```
+
+### Generated State
+
+```typescript
+interface EntitySliceState<T> {
+  [entityName]: T[];      // Entity data array
+  loading: boolean;       // Loading indicator
+  count: number;          // Total count for pagination
+  refetch: boolean;       // Trigger refetch flag
+  rolesWidgets: unknown[];// Widgets (for roles slice)
+  notify: NotificationState;
+}
+
+interface NotificationState {
+  showNotification: boolean;
+  textNotification: string;
+  typeNotification: 'warn' | 'error' | 'success' | 'info' | '';
+}
+```
+
+### Generated Async Thunks
+
+| Thunk | Action Type | Purpose |
+|-------|-------------|---------|
+| `fetch` | `{name}/fetch` | Fetch single by ID or list with query |
+| `create` | `{name}/create{Name}` | Create new entity |
+| `update` | `{name}/update{Name}` | Update existing entity |
+| `deleteItem` | `{name}/delete{Name}` | Delete single entity |
+| `deleteItemsByIds` | `{name}/deleteByIds` | Bulk delete by IDs |
+| `uploadCsv` | `{name}/uploadCsv` | Import CSV file |
+
+### Generated Reducers
+
+| Reducer | Purpose |
+|---------|---------|
+| `setRefetch` | Trigger data refetch |
+
+### Usage Example
+
+```typescript
+// Creating a slice (entity file)
+import { createEntitySlice } from '../createEntitySlice';
+import type { User } from '../../types/entities';
+
+const { slice, actions, reducer } = createEntitySlice<User>({
+  name: 'users',
+  endpoint: 'users',
+  singularName: 'User',
+});
+
+export const {
+  fetch,
+  create,
+  update,
+  deleteItem,
+  deleteItemsByIds,
+  uploadCsv,
+  setRefetch,
+} = actions;
+
+export default reducer;
+```
+
+```typescript
+// Using in components
+import { useAppDispatch, useAppSelector } from '../stores/hooks';
+import { fetch, create, update, deleteItem } from '../stores/users/usersSlice';
+
+const UsersPage = () => {
+  const dispatch = useAppDispatch();
+  const { users, loading, count, notify } = useAppSelector((state) => state.users);
+
+  // Fetch list with pagination
+  useEffect(() => {
+    dispatch(fetch({ query: '?page=1&limit=10' }));
+  }, []);
+
+  // Fetch single by ID
+  const loadUser = (id: string) => {
+    dispatch(fetch({ id }));
+  };
+
+  // Create new
+  const createUser = (data: Partial<User>) => {
+    dispatch(create(data));
+  };
+
+  // Update existing
+  const updateUser = (id: string, data: Partial<User>) => {
+    dispatch(update({ id, data }));
+  };
+
+  // Delete
+  const removeUser = (id: string) => {
+    dispatch(deleteItem(id));
+  };
+};
+```
+
+### Factory Implementation Details
+
+```typescript
+// Fetch thunk handles both single and list
+const fetch = createAsyncThunk<
+  T | PaginatedResponse<T>,
+  FetchParams,
+  { rejectValue: ApiError }
+>(`${name}/fetch`, async (data: FetchParams) => {
+  const { id, query } = data;
+  const url = `${endpoint}${query || (id ? `/${id}` : '')}`;
+  const result = await axios.get<T | PaginatedResponse<T>>(url);
+
+  if (id) {
+    return result.data as T;  // Single entity
+  }
+
+  return {
+    rows: (result.data as PaginatedResponse<T>).rows,
+    count: (result.data as PaginatedResponse<T>).count,
+  };
+});
+
+// Extrareducers handle state updates
+builder.addCase(fetch.fulfilled, (state, action) => {
+  const payload = action.payload;
+  if (isPaginatedResponse<T>(payload)) {
+    state[name] = payload.rows;
+    state.count = payload.count;
+  } else {
+    state[name] = payload;  // Single entity stored in array
+  }
+  state.loading = false;
+});
+```
+
+---
+
+## Core Slices
+
+### 1. authSlice
+
+**File:** `authSlice.ts` (~130 LOC)
+
+**Purpose:** Authentication state management.
+
+```typescript
+interface AuthState {
+  isFetching: boolean;
+  errorMessage: string;
+  currentUser: User | null;
+  token: string;
+  notify: NotificationState;
+}
+```
+
+**Async Thunks:**
+
+| Thunk | Endpoint | Purpose |
+|-------|----------|---------|
+| `loginUser` | `POST /auth/signin/local` | Local authentication |
+| `findMe` | `GET /auth/me` | Fetch current user |
+| `passwordReset` | `PUT /auth/password-reset` | Reset password |
+
+**Reducers:**
+
+| Reducer | Purpose |
+|---------|---------|
+| `logoutUser` | Clear auth state, remove tokens |
+
+**Token Handling:**
+```typescript
+builder.addCase(loginUser.fulfilled, (state, action) => {
+  const token = action.payload;
+  const user = jwt.decode(token);
+
+  state.token = token;
+  sessionStorage.setItem('token', token);
+  localStorage.setItem('token', token);
+  axios.defaults.headers.common['Authorization'] = 'Bearer ' + token;
+});
+```
+
+**Usage:**
+```typescript
+import { loginUser, logoutUser, findMe } from '../stores/authSlice';
+
+// Login
+dispatch(loginUser({ email, password }));
+
+// Logout
+dispatch(logoutUser());
+
+// Fetch current user
+dispatch(findMe());
+
+// Access state
+const { currentUser, isFetching, errorMessage } = useAppSelector(state => state.auth);
+```
+
+---
+
+### 2. styleSlice
+
+**File:** `styleSlice.ts` (~107 LOC)
+
+**Purpose:** UI theming and styling state.
+
+```typescript
+interface StyleState {
+  darkMode: boolean;
+  bgLayoutColor: string;
+  iconsColor: string;
+  activeLinkColor: string;
+  cardsColor: string;
+  focusRingColor: string;
+  corners: string;
+  cardsStyle: string;
+  linkColor: string;
+  borders: string;
+  shadow: string;
+  textSecondary: string;
+  // Aside menu styles
+  asideStyle: string;
+  asideScrollbarsStyle: string;
+  asideBrandStyle: string;
+  asideMenuItemStyle: string;
+  asideMenuItemActiveStyle: string;
+  asideMenuDropdownStyle: string;
+  // NavBar styles
+  navBarItemLabelStyle: string;
+  navBarItemLabelHoverStyle: string;
+  navBarItemLabelActiveColorStyle: string;
+  overlayStyle: string;
+  websiteHeder: string;
+  websiteSectionStyle: string;
+}
+```
+
+**Reducers:**
+
+| Reducer | Purpose |
+|---------|---------|
+| `setDarkMode` | Toggle dark/light mode |
+| `setStyle` | Apply complete style theme |
+
+**Dark Mode Handling:**
+```typescript
+setDarkMode: (state, action: PayloadAction<boolean | null>) => {
+  state.darkMode = action.payload !== null ? action.payload : !state.darkMode;
+
+  localStorage.setItem(localStorageDarkModeKey, state.darkMode ? '1' : '0');
+
+  document.body.classList[state.darkMode ? 'add' : 'remove']('dark-scrollbars');
+  document.documentElement.classList[state.darkMode ? 'add' : 'remove']('dark-scrollbars-compat');
+}
+```
+
+**Usage:**
+```typescript
+import { setDarkMode, setStyle } from '../stores/styleSlice';
+
+// Toggle dark mode
+dispatch(setDarkMode(null)); // Toggle
+dispatch(setDarkMode(true)); // Force dark
+dispatch(setDarkMode(false)); // Force light
+
+// Apply style theme
+dispatch(setStyle('white'));
+dispatch(setStyle('basic'));
+
+// Access state
+const { darkMode, corners, cardsStyle, iconsColor } = useAppSelector(state => state.style);
+```
+
+---
+
+### 3. mainSlice
+
+**File:** `mainSlice.ts` (~36 LOC)
+
+**Purpose:** Main application UI state.
+
+```typescript
+interface MainState {
+  userName: string;
+  userEmail: string | null;
+  userAvatar: string | null;
+  isFieldFocusRegistered: boolean;
+}
+```
+
+**Reducers:**
+
+| Reducer | Purpose |
+|---------|---------|
+| `setUser` | Update user display info |
+
+**Usage:**
+```typescript
+import { setUser } from '../stores/mainSlice';
+
+dispatch(setUser({
+  name: 'John Doe',
+  email: 'john@example.com',
+  avatar: '/avatars/john.jpg',
+}));
+
+const { userName, userEmail, userAvatar } = useAppSelector(state => state.main);
+```
+
+---
+
+## Entity Slices
+
+All 13 entity slices follow the factory pattern:
+
+### Standard Entity Slice Pattern
+
+```typescript
+/**
+ * {Entity} Redux Slice
+ */
+
+import { createEntitySlice } from '../createEntitySlice';
+import type { EntityType } from '../../types/entities';
+
+const { slice, actions, reducer } = createEntitySlice<EntityType>({
+  name: 'entity_name',
+  endpoint: 'api_endpoint',
+  singularName: 'Entity Name',
+});
+
+export const {
+  fetch,
+  create,
+  update,
+  deleteItem,
+  deleteItemsByIds,
+  uploadCsv,
+  setRefetch,
+} = actions;
+
+export const entitySlice = slice;
+export default reducer;
+```
+
+### Entity Slice Inventory
+
+| Slice | Entity Type | Endpoint | Singular Name |
+|-------|-------------|----------|---------------|
+| `users` | `User` | `users` | User |
+| `roles` | `Role` | `roles` | Role |
+| `permissions` | `PermissionEntity` | `permissions` | Permission |
+| `projects` | `Project` | `projects` | Project |
+| `project_memberships` | `ProjectMembership` | `project_memberships` | Project Membership |
+| `assets` | `Asset` | `assets` | Asset |
+| `asset_variants` | `AssetVariant` | `asset_variants` | Asset Variant |
+| `presigned_url_requests` | `PresignedUrlRequest` | `presigned_url_requests` | Presigned URL Request |
+| `tour_pages` | `TourPage` | `tour_pages` | Tour Page |
+| `project_audio_tracks` | `ProjectAudioTrack` | `project_audio_tracks` | Project Audio Track |
+| `publish_events` | `PublishEvent` | `publish_events` | Publish Event |
+| `pwa_caches` | `PwaCache` | `pwa_caches` | PWA Cache |
+| `access_logs` | `AccessLog` | `access_logs` | Access Log |
+| `global_transition_defaults` | `GlobalTransitionDefaults` | `global-transition-defaults` | Global defaults (singleton, public GET) |
+| `project_transition_settings` | `ProjectTransitionSettingsEntity` | `project-transition-settings` | Per-project settings (public prod GET) |
+
+## Type Definitions
+
+### Redux Types (`types/redux.ts`)
+
+```typescript
+// Notification state structure
+export interface NotificationState {
+  showNotification: boolean;
+  textNotification: string;
+  typeNotification: 'warn' | 'error' | 'success' | 'info' | '';
+}
+
+// Generic entity slice state
+export interface EntitySliceState<T> {
+  data: T[];
+  loading: boolean;
+  count: number;
+  refetch: boolean;
+  notify: NotificationState;
+}
+
+// Slice factory configuration
+export interface EntitySliceConfig {
+  name: string;
+  endpoint: string;
+  singularName?: string;
+}
+
+// Auth state structure
+export interface AuthState {
+  currentUser: User | null;
+  token: string | null;
+  isFetching: boolean;
+  errorMessage: string | null;
+  notify: NotificationState;
+}
+```
+
+### API Types (`types/api.ts`)
+
+```typescript
+// Paginated response from API
+export interface PaginatedResponse<T> {
+  rows: T[];
+  count: number;
+}
+
+// Fetch parameters for entity queries
+export interface FetchParams {
+  id?: string;
+  query?: string;
+  limit?: number;
+  page?: number;
+}
+
+// API error response structure
+export interface ApiError {
+  message?: string;
+  statusCode?: number;
+  errors?: Record<string, { _errors: string[] }>;
+}
+
+// Sort model for data grid
+export interface SortModel {
+  field: string;
+  sort: 'asc' | 'desc';
+}
+
+// Query parameters for list requests
+export interface ListQueryParams {
+  page?: number;
+  limit?: number;
+  sort?: 'asc' | 'desc';
+  field?: string;
+  [filterKey: string]: string | number | boolean | undefined;
+}
+```
+
+### Entity Types (`types/entities.ts`)
+
+```typescript
+// Base entity interface
+export interface BaseEntity {
+  id: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+// User entity
+export interface User extends BaseEntity {
+  firstName?: string;
+  lastName?: string;
+  email: string;
+  disabled?: boolean;
+  avatar?: ImageFile[];
+  app_role?: Role | null;
+  custom_permissions?: PermissionEntity[];
+}
+
+// Project entity
+export interface Project extends BaseEntity {
+  name: string;
+  slug?: string;
+  description?: string;
+  logo_url?: string;
+  favicon_url?: string;
+  og_image_url?: string;
+}
+
+// Asset entity
+export interface Asset extends BaseEntity {
+  project?: Project | string | null;
+  name: string;
+  asset_type: 'image' | 'video' | 'audio' | 'file';
+  type?: 'general' | 'icon' | 'background_image' | 'audio' | 'video' | 'transition' | 'logo' | 'favicon' | 'document';
+  cdn_url?: string;
+  storage_key?: string;
+  mime_type?: string;
+  size_mb?: number;
+  width_px?: number;
+  height_px?: number;
+  duration_sec?: number;
+  is_public?: boolean;
+  is_deleted?: boolean;
+}
+
+// ... (13 total entity types)
+```
+
+---
+
+## Notification Helpers
+
+**File:** `helpers/notifyStateHandler.ts`
+
+Utility functions for managing notification state:
+
+```typescript
+// Reset notification state
+export const resetNotify = (state) => {
+  state.notify.showNotification = false;
+  state.notify.typeNotification = '';
+  state.notify.textNotification = '';
+};
+
+// Handle rejected action with error notification
+export const rejectNotify = (state, action) => {
+  if (typeof action.payload === 'string') {
+    state.notify.textNotification = action.payload;
+  } else if (typeof action === 'object') {
+    // Parse validation errors
+    const obj = { ...action.payload?.errors };
+    delete obj['_errors'];
+
+    let msg = '';
+    for (const key in obj) {
+      msg += `${key}: ${obj[key]['_errors']}; \n `;
+    }
+    state.notify.textNotification = msg;
+  } else {
+    state.notify.textNotification = 'Network error';
+  }
+
+  state.notify.typeNotification = 'error';
+  state.notify.showNotification = true;
+};
+
+// Handle fulfilled action with success notification
+export const fulfilledNotify = (state, msg) => {
+  state.notify.textNotification = msg;
+  state.notify.typeNotification = 'success';
+  state.notify.showNotification = true;
+};
+```
+
+---
+
+## Onboarding Tour Steps
+
+**File:** `introSteps.ts` (~135 LOC)
+
+Defines step configurations for the app onboarding tour:
+
+```typescript
+interface Step {
+  element: string;        // CSS selector
+  intro: string;          // HTML content
+  position?: string;      // Tooltip position
+  tooltipClass?: string;  // Custom CSS class
+  disableInteraction?: boolean;
+}
+
+// Exported step arrays
+export const loginSteps: Step[] = [...];  // Login page tour
+export const appSteps: Step[] = [...];    // Main app tour
+export const usersSteps: Step[] = [...];  // Users page tour
+export const rolesSteps: Step[] = [...];  // Roles page tour
+```
+
+---
+
+## Data Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Component                                │
+│  useAppDispatch() + useAppSelector()                           │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      │ dispatch(fetch({ query }))
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Async Thunk                                 │
+│  fetch, create, update, deleteItem, etc.                        │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      │ axios.get/post/put/delete
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Backend API                                 │
+│  /api/{endpoint}                                                │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      │ Response
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Extra Reducers                                │
+│  pending → loading: true                                        │
+│  fulfilled → data: payload, loading: false                      │
+│  rejected → notify: error, loading: false                       │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      │ State update
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Store                                       │
+│  RootState with 17 slices                                       │
+└─────────────────────┬───────────────────────────────────────────┘
+                      │
+                      │ useAppSelector subscription
+                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Component Re-render                          │
+│  UI updates with new data                                       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Usage Patterns
+
+### 1. List Page Pattern
+
+```typescript
+import { useEffect } from 'react';
+import { useAppDispatch, useAppSelector } from '../stores/hooks';
+import { fetch, setRefetch } from '../stores/users/usersSlice';
+
+const UsersListPage = () => {
+  const dispatch = useAppDispatch();
+  const { users, loading, count, refetch } = useAppSelector(state => state.users);
+  const [page, setPage] = useState(1);
+
+  // Initial fetch
+  useEffect(() => {
+    dispatch(fetch({ query: `?page=${page}&limit=10` }));
+  }, [page, dispatch]);
+
+  // Refetch trigger
+  useEffect(() => {
+    if (refetch) {
+      dispatch(fetch({ query: `?page=${page}&limit=10` }));
+      dispatch(setRefetch(false));
+    }
+  }, [refetch, page, dispatch]);
+
+  return (
+    <DataGrid
+      rows={users}
+      loading={loading}
+      rowCount={count}
+      onPageChange={setPage}
+    />
+  );
+};
+```
+
+### 2. Edit Page Pattern
+
+```typescript
+import { useEffect, useState } from 'react';
+import { useRouter } from 'next/router';
+import { useAppDispatch, useAppSelector } from '../stores/hooks';
+import { fetch, update } from '../stores/users/usersSlice';
+
+const UserEditPage = () => {
+  const router = useRouter();
+  const { id } = router.query;
+  const dispatch = useAppDispatch();
+  const { users, loading, notify } = useAppSelector(state => state.users);
+
+  // Fetch entity on mount
+  useEffect(() => {
+    if (id) {
+      dispatch(fetch({ id: id as string }));
+    }
+  }, [id, dispatch]);
+
+  // Get current entity
+  const user = Array.isArray(users) ? users[0] : users;
+
+  const handleSubmit = async (data: Partial<User>) => {
+    await dispatch(update({ id: id as string, data }));
+    router.push('/users/users-list');
+  };
+
+  return (
+    <Formik initialValues={user} onSubmit={handleSubmit}>
+      {/* Form fields */}
+    </Formik>
+  );
+};
+```
+
+### 3. Create Page Pattern
+
+```typescript
+import { useAppDispatch, useAppSelector } from '../stores/hooks';
+import { create } from '../stores/users/usersSlice';
+
+const UserNewPage = () => {
+  const dispatch = useAppDispatch();
+  const router = useRouter();
+  const { loading, notify } = useAppSelector(state => state.users);
+
+  const handleSubmit = async (data: Partial<User>) => {
+    const result = await dispatch(create(data));
+    if (result.meta.requestStatus === 'fulfilled') {
+      router.push('/users/users-list');
+    }
+  };
+
+  return (
+    <Formik initialValues={{}} onSubmit={handleSubmit}>
+      {/* Form fields */}
+    </Formik>
+  );
+};
+```
+
+### 4. Delete Pattern
+
+```typescript
+import { deleteItem, deleteItemsByIds, setRefetch } from '../stores/users/usersSlice';
+
+// Delete single
+const handleDelete = async (id: string) => {
+  await dispatch(deleteItem(id));
+  dispatch(setRefetch(true));
+};
+
+// Bulk delete
+const handleBulkDelete = async (ids: string[]) => {
+  await dispatch(deleteItemsByIds(ids));
+  dispatch(setRefetch(true));
+};
+```
+
+### 5. Notification Handling
+
+```typescript
+import { useEffect } from 'react';
+import { toast } from 'react-toastify';
+
+const MyComponent = () => {
+  const { notify } = useAppSelector(state => state.users);
+
+  useEffect(() => {
+    if (notify.showNotification) {
+      if (notify.typeNotification === 'success') {
+        toast.success(notify.textNotification);
+      } else if (notify.typeNotification === 'error') {
+        toast.error(notify.textNotification);
+      }
+    }
+  }, [notify]);
+};
+```
+
+---
+
+## Store Provider Setup
+
+**File:** `_app.tsx`
+
+```typescript
+import { Provider } from 'react-redux';
+import { store } from '../stores/store';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <Provider store={store}>
+      <Component {...pageProps} />
+    </Provider>
+  );
+}
+
+export default MyApp;
+```
+
+---
+
+## State Management Guidelines
+
+### When to Use Redux (Default)
+
+Redux is the **default choice** for application state. Use Redux slices for:
+
+| State Type | Example | Why Redux |
+|------------|---------|-----------|
+| **Entity Data** | Users, Projects, Assets, Tour Pages | Shared across multiple components, API-backed |
+| **Authentication** | Current user, JWT token | App-wide, persisted to localStorage |
+| **UI Preferences** | Dark mode, theme settings | Persisted, affects entire app |
+| **Form State** | Complex multi-step forms | Survives navigation, shareable |
+| **Notifications** | Toast messages | Triggered from anywhere |
+
+### When Local Hooks Are Acceptable
+
+Local React hooks (`useState`, custom hooks) are appropriate for:
+
+| State Type | Example | Why Local |
+|------------|---------|-----------|
+| **Ephemeral UI State** | Modal open/closed, dropdown expanded | Component-scoped, no persistence needed |
+| **Session-Scoped Navigation** | Page history in `usePageNavigation` | Isolated to single route, resets on unmount |
+| **Animation State** | Transition progress, fade states | Highly transient, no sharing needed |
+| **Form Field Focus** | Which input is focused | Local to form component |
+| **Derived/Computed Values** | Filtered lists, sorted data | Computed from Redux state |
+
+### Decision Tree
+
+```
+Is the state needed by multiple unrelated components?
+├── Yes → Use Redux
+└── No → Does the state need to persist across route changes?
+         ├── Yes → Use Redux
+         └── No → Is the state tied to API data?
+                  ├── Yes → Use Redux
+                  └── No → Local hook is acceptable
+```
+
+### Example: usePageNavigation (Local Hook)
+
+The `usePageNavigation` hook uses local `useState` because:
+- ✅ Only used by RuntimePresentation OR constructor (never both simultaneously)
+- ✅ Session-scoped - history resets when leaving the tour
+- ✅ No cross-component sharing needed
+- ✅ No persistence requirement
+- ✅ Simple data structure (array + string)
+
+```typescript
+// Appropriate for local hook
+const { currentPageId, pageHistory, applyPageSelection } = usePageNavigation({
+  pages,
+  trackHistory: true,
+});
+```
+
+### Example: Constructor Elements (Redux)
+
+The `constructorSlice` uses Redux because:
+- ✅ Multiple components need access (canvas, sidebar, settings panels)
+- ✅ Complex nested state (elements, selections, undo history)
+- ✅ DevTools debugging valuable
+- ✅ Actions dispatched from many places
+
+```typescript
+// Appropriate for Redux
+const elements = useAppSelector((state) => state.constructor.elements);
+dispatch(updateElement({ id, changes }));
+```
+
+### Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| Redux for modal open/close | Over-engineering | Local `useState` |
+| Local state for entity data | Data inconsistency | Redux slice |
+| Prop drilling 3+ levels | Maintenance burden | Redux or Context |
+| Redux for animation frames | Performance issues | Local `useRef` |
+
+---
+
+## Summary
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| Core Slices | 4 | auth, style, main, openAi |
+| Entity Slices | 15 | Generated via factory pattern (includes 2 transition slices) |
+| Constructor Slice | 1 | Tour editor state |
+| Type Files | 3 | redux.ts, entities.ts, api.ts |
+| Total Slices | 20 | Combined in store.ts |
+
+### Public Access Slices
+
+Some slices support public API access for runtime presentations:
+
+| Slice | Public Access | Notes |
+|-------|--------------|-------|
+| `global_transition_defaults` | GET always public | No auth headers needed |
+| `project_transition_settings` | GET production only | Backend determines from URL path |
+
+These slices don't require special headers - the backend determines public access from the URL path itself.
+| Total Files | 22+ | In stores directory |
+
+**Key Patterns:**
+- **Redux is default** for app-wide, persistent, shared state
+- **Local hooks acceptable** for ephemeral, component-scoped state
+- Factory pattern eliminates ~2,600 LOC of boilerplate (13 entities × ~200 LOC each)
+- Typed hooks ensure type safety throughout
+- Consistent notification handling via helpers
+- Async thunks with proper error handling
+
+---
+
+## Related Documentation
+
+- [Frontend Architecture](./frontend-architecture.md) - Overall frontend structure
+- [Hooks Module](./hooks-module.md) - Custom React hooks
+- [Components Module](./components-module.md) - React components
+- [Backend API Endpoints](../../backend/docs/api-endpoints.md) - API reference
diff --git a/frontend/docs/types-module.md b/frontend/docs/types-module.md
new file mode 100644
index 0000000..e586202
--- /dev/null
+++ b/frontend/docs/types-module.md
@@ -0,0 +1,1435 @@
+# Types Module
+
+## Overview
+
+The types module provides **TypeScript type definitions** used throughout the frontend application. These types ensure type safety, enable IDE autocompletion, and document the data structures used across components, hooks, stores, and API interactions.
+
+**Location:** `frontend/src/types/`
+
+**Statistics:**
+- **19 files** (~2,110 LOC total)
+- **6 categories**: Domain Entities, Runtime/Presentation, Infrastructure, Forms/Filters, Specialized, Module Declarations
+- Central export via `index.ts`
+
+---
+
+## Architecture Diagram
+
+```
+frontend/src/types/
+├── index.ts                # Central re-export (14 LOC)
+│
+├── Domain Entities
+│   ├── entities.ts         # Database entity types (307 LOC)
+│   ├── constructor.ts      # Canvas element types (418 LOC)
+│   └── permissions.ts      # RBAC permission enum (122 LOC)
+│
+├── Runtime & Presentation
+│   ├── runtime.ts          # Runtime page/project types (92 LOC)
+│   ├── presentation.ts     # Navigation/transition types (107 LOC)
+│   ├── uiControls.ts       # Global UI-control cascade/settings types
+│   └── preload.ts          # Preload infrastructure types (57 LOC)
+│
+├── Infrastructure
+│   ├── offline.ts          # PWA/offline storage types (194 LOC)
+│   ├── api.ts              # API request/response types (62 LOC)
+│   └── redux.ts            # Redux state types (60 LOC)
+│
+├── Forms & Filters
+│   ├── forms.ts            # Form configuration types (76 LOC)
+│   └── filters.ts          # Table filter types (74 LOC)
+│
+├── Specialized
+│   ├── charts.ts           # Chart/dashboard data types (42 LOC)
+│   ├── components.ts       # UI component prop types (30 LOC)
+│   ├── menu.ts             # Navigation menu types (25 LOC)
+│   └── ui.ts               # Generic UI element types (35 LOC)
+│
+└── Module Declarations
+    └── css.d.ts            # CSS module type declarations (10 LOC)
+```
+
+---
+
+## Type Categories
+
+### 1. Domain Entities (`entities.ts`)
+
+Core database entity types that mirror backend Sequelize models.
+
+#### BaseEntity
+```typescript
+export interface BaseEntity {
+  id: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+```
+
+#### User Entity
+```typescript
+export interface User extends BaseEntity {
+  firstName?: string;
+  lastName?: string;
+  phoneNumber?: string;
+  email: string;
+  disabled?: boolean;
+  avatar?: ImageFile[];
+  app_role?: Role | null;
+  custom_permissions?: PermissionEntity[];
+  password?: string;
+}
+```
+
+#### Project Entity
+```typescript
+export interface Project extends BaseEntity {
+  name: string;
+  slug?: string;
+  description?: string;
+  logo_url?: string;
+  favicon_url?: string;
+  og_image_url?: string;
+  design_width?: number;    // Design canvas width (default 1920)
+  design_height?: number;   // Design canvas height (default 1080)
+  is_deleted?: boolean;
+  deleted_at_time?: string | Date | null;
+}
+```
+
+#### Asset Entity
+```typescript
+export interface Asset extends BaseEntity {
+  project?: Project | string | null;
+  name: string;
+  asset_type: 'image' | 'video' | 'audio' | 'file';
+  type?: 'general' | 'icon' | 'background_image' | 'audio' | 'video'
+       | 'transition' | 'logo' | 'favicon' | 'document';
+  cdn_url?: string;
+  storage_key?: string;
+  mime_type?: string;
+  size_mb?: number;
+  width_px?: number;
+  height_px?: number;
+  duration_sec?: number;
+  checksum?: string;
+  is_public?: boolean;
+  is_deleted?: boolean;
+  deleted_at_time?: string | Date;
+}
+```
+
+#### TourPage Entity
+```typescript
+export interface TourPage extends BaseEntity {
+  project?: Project | string | null;
+  name?: string;
+  title?: string;
+  slug?: string;
+  background_asset?: Asset | string | null;
+  audio_asset?: Asset | string | null;
+  is_start_page?: boolean;
+  sort_order?: number;
+  environment?: 'dev' | 'stage' | 'production';
+  source_key?: string;
+  requires_auth?: boolean;
+  ui_schema_json?: string;
+  // Background URL fields (direct storage paths)
+  background_image_url?: string;
+  background_video_url?: string;
+  background_audio_url?: string;
+  background_loop?: boolean;
+  // Background video playback settings
+  background_video_autoplay?: boolean;
+  background_video_loop?: boolean;
+  background_video_muted?: boolean;
+  background_video_start_time?: number | null;
+  background_video_end_time?: number | null;
+  // Background audio playback settings
+  background_audio_autoplay?: boolean;
+  background_audio_loop?: boolean;
+  background_audio_start_time?: number | null;
+  background_audio_end_time?: number | null;
+  // Design canvas dimensions (copied from project on save)
+  design_width?: number | null;
+  design_height?: number | null;
+}
+```
+
+#### Complete Entity List
+
+| Entity | Description |
+|--------|-------------|
+| `User` | User accounts with roles and permissions |
+| `Role` | Role definitions with permission sets |
+| `PermissionEntity` | Individual permission records |
+| `Project` | Tour projects with configuration |
+| `Asset` | Media assets (images, videos, audio) |
+| `AssetVariant` | Variant versions (thumbnails, previews) |
+| `TourPage` | Tour pages with backgrounds |
+| `PageElement` | UI elements on pages |
+| `PageLink` | Navigation links between pages |
+| `Transition` | Video transitions |
+| `ProjectAudioTrack` | Background audio tracks |
+| `ProjectMembership` | User-project access |
+| `PublishEvent` | Publishing history |
+| `PwaCache` | PWA cache tracking |
+| `PresignedUrlRequest` | File upload/download requests |
+| `AccessLog` | Audit trail entries |
+| `UIElement` | Generic UI element |
+
+#### Entity Type Map
+```typescript
+// Type-safe entity name to type mapping
+export type EntityName =
+  | 'users' | 'roles' | 'permissions' | 'projects'
+  | 'project_memberships' | 'assets' | 'asset_variants'
+  | 'tour_pages' | 'project_audio_tracks' | 'publish_events'
+  | 'pwa_caches' | 'presigned_url_requests' | 'access_logs'
+  | 'element_type_defaults';
+
+export interface EntityTypeMap {
+  users: User;
+  roles: Role;
+  permissions: PermissionEntity;
+  projects: Project;
+  // ... all entities mapped
+}
+```
+
+---
+
+### 2. Constructor Types (`constructor.ts`)
+
+Types for the tour builder (constructor) page and UI elements.
+
+#### Canvas Element Types
+```typescript
+// 11 available element types
+export type CanvasElementType =
+  | 'navigation_next'  // Forward navigation button
+  | 'navigation_prev'  // Back navigation button
+  | 'spot'             // Hotspot/clickable area
+  | 'description'      // Text description block
+  | 'tooltip'          // Hover tooltip
+  | 'gallery'          // Image gallery
+  | 'carousel'         // Image carousel
+  | 'logo'             // Logo element
+  | 'video_player'     // Video player
+  | 'audio_player'     // Audio player
+  | 'popup';           // Popup/modal
+```
+
+#### CanvasElement Interface
+```typescript
+export interface CanvasElement extends BaseCanvasElement {
+  type: CanvasElementType;
+  label: string;
+  xPercent: number;
+  yPercent: number;
+
+  // Icon
+  iconUrl?: string;
+
+  // Media
+  mediaUrl?: string;
+  mediaAutoplay?: boolean;
+  mediaLoop?: boolean;
+  mediaMuted?: boolean;
+
+  // Background
+  backgroundImageUrl?: string;
+  videoUrl?: string;
+  audioUrl?: string;
+
+  // Gallery/Carousel
+  galleryCards?: GalleryCard[];
+  galleryHeaderImageUrl?: string;
+  galleryTitle?: string;
+  galleryInfoSpans?: GalleryInfoSpan[];
+  galleryColumns?: number;
+  galleryTitleFontFamily?: string;
+  galleryCardFontFamily?: string;
+  carouselSlides?: CarouselSlide[];
+  carouselCaptionFontFamily?: string;
+  carouselPrevIconUrl?: string;
+  carouselNextIconUrl?: string;
+
+  // Gallery Carousel Settings (button icons, positions, dimensions)
+  galleryCarouselPrevIconUrl?: string;
+  galleryCarouselNextIconUrl?: string;
+  galleryCarouselBackIconUrl?: string;
+  galleryCarouselBackLabel?: string;
+  galleryCarouselPrevX?: number;
+  galleryCarouselPrevY?: number;
+  galleryCarouselNextX?: number;
+  galleryCarouselNextY?: number;
+  galleryCarouselBackX?: number;
+  galleryCarouselBackY?: number;
+  galleryCarouselPrevWidth?: string;
+  galleryCarouselPrevHeight?: string;
+  galleryCarouselNextWidth?: string;
+  galleryCarouselNextHeight?: string;
+  galleryCarouselBackWidth?: string;
+  galleryCarouselBackHeight?: string;
+
+  // Info Panel trigger/default behavior
+  infoPanelTriggerLabel?: string;
+  infoPanelTriggerFontFamily?: string;
+  infoPanelDisabled?: boolean;
+  infoPanelOpenByDefault?: boolean;
+
+  // Tooltip
+  tooltipTitle?: string;
+  tooltipText?: string;
+  tooltipTitleFontFamily?: string;
+  tooltipTextFontFamily?: string;
+
+  // Description
+  descriptionTitle?: string;
+  descriptionText?: string;
+  descriptionTitleFontSize?: string;
+  descriptionTextFontSize?: string;
+  descriptionTitleFontFamily?: string;
+  descriptionTextFontFamily?: string;
+  descriptionTitleColor?: string;
+  descriptionTextColor?: string;
+  descriptionBackgroundColor?: string;
+
+  // Navigation
+  navLabel?: string;
+  navType?: NavigationButtonKind;
+  navDisabled?: boolean;
+  /** @deprecated Use targetPageSlug instead */
+  targetPageId?: string;
+  targetPageSlug?: string;
+  transitionVideoUrl?: string;
+  transitionReverseMode?: 'auto_reverse' | 'separate_video';
+  reverseVideoUrl?: string;
+  transitionDurationSec?: number;
+}
+```
+
+#### Gallery & Carousel Items
+```typescript
+export interface GalleryCard {
+  id: string;
+  imageUrl: string;
+  title: string;
+  description: string;
+}
+
+export interface GalleryInfoSpan {
+  id: string;
+  text: string;
+}
+
+export interface CarouselSlide {
+  id: string;
+  imageUrl: string;
+  caption: string;
+}
+```
+
+#### Constructor Schema & Asset Types
+```typescript
+export interface ConstructorSchema {
+  elements?: CanvasElement[];
+}
+
+export interface ConstructorAsset {
+  id: string;
+  name?: string;
+  asset_type?: 'image' | 'video' | 'audio' | 'file';
+  type?: 'icon' | 'background_image' | 'audio' | 'video'
+       | 'transition' | 'logo' | 'favicon' | 'document' | 'general';
+  cdn_url?: string | null;
+  storage_key?: string | null;
+}
+
+export interface AssetOption {
+  value: string;
+  label: string;
+}
+```
+
+#### Type Guards
+```typescript
+// Type guard for canvas element types
+export function isCanvasElementType(value: string): value is CanvasElementType {
+  return CANVAS_ELEMENT_TYPES.includes(value as CanvasElementType);
+}
+```
+
+#### Element Default Normalization
+```typescript
+// Normalize API response to consistent format
+export function normalizeElementDefault(
+  row: Record<string, unknown>,
+): NormalizedElementDefault | null;
+
+// Build lookup map from defaults array
+export function buildElementDefaultsMap(
+  defaults: NormalizedElementDefault[],
+): Partial<Record<CanvasElementType, Partial<CanvasElement>>>;
+```
+
+#### Page Background State Types
+```typescript
+// Video playback settings
+export interface PageBackgroundVideoSettings {
+  autoplay: boolean;
+  loop: boolean;
+  muted: boolean;
+  startTime: number | null;
+  endTime: number | null;
+}
+
+// Audio playback settings
+export interface PageBackgroundAudioSettings {
+  autoplay: boolean;
+  loop: boolean;
+  startTime: number | null;
+  endTime: number | null;
+}
+
+// Consolidated background state (replaces 8 useState hooks)
+export interface PageBackgroundState {
+  imageUrl: string;
+  videoUrl: string;
+  audioUrl: string;
+  videoSettings: PageBackgroundVideoSettings;
+  audioSettings: PageBackgroundAudioSettings;
+}
+
+// Default constants
+export const DEFAULT_VIDEO_SETTINGS: PageBackgroundVideoSettings;
+export const DEFAULT_AUDIO_SETTINGS: PageBackgroundAudioSettings;
+export const DEFAULT_PAGE_BACKGROUND: PageBackgroundState;
+
+// Factory function
+export function createPageBackgroundFromPage(
+  page: TourPage | null
+): PageBackgroundState;
+```
+
+#### Editor Panel Props
+The constructor types also define grouped props interfaces for the `ElementEditorPanel`:
+
+| Interface | Purpose |
+|-----------|---------|
+| `EditorLayoutProps` | Panel position and collapse state |
+| `EditorStateProps` | Tabs and title |
+| `EditorElementProps` | Selected element and callbacks |
+| `EditorBackgroundProps` | Background image/video/audio URLs |
+| `EditorTransitionProps` | Transition creation state |
+| `EditorDurationNotesProps` | Duration display notes |
+| `EditorAssetOptionsProps` | Asset dropdown options |
+| `EditorNavigationProps` | Navigation settings |
+| `EditorCollectionOpsProps` | Gallery/carousel operations |
+| `EditorMediaUtilsProps` | Duration utilities |
+
+---
+
+### 3. Permissions (`permissions.ts`)
+
+RBAC (Role-Based Access Control) permission definitions.
+
+#### Permission Enum
+```typescript
+export enum Permission {
+  // User permissions
+  READ_USERS = 'READ_USERS',
+  CREATE_USERS = 'CREATE_USERS',
+  UPDATE_USERS = 'UPDATE_USERS',
+  DELETE_USERS = 'DELETE_USERS',
+
+  // Role permissions
+  READ_ROLES = 'READ_ROLES',
+  CREATE_ROLES = 'CREATE_ROLES',
+  UPDATE_ROLES = 'UPDATE_ROLES',
+  DELETE_ROLES = 'DELETE_ROLES',
+
+  // Project permissions
+  READ_PROJECTS = 'READ_PROJECTS',
+  CREATE_PROJECTS = 'CREATE_PROJECTS',
+  UPDATE_PROJECTS = 'UPDATE_PROJECTS',
+  DELETE_PROJECTS = 'DELETE_PROJECTS',
+
+  // ... 60+ total permissions covering all entities
+}
+```
+
+#### Permission Helper
+```typescript
+// Generate CRUD permissions for any entity
+export const getEntityPermissions = (entityName: string) => {
+  const uppercased = entityName.toUpperCase();
+  return {
+    read: `READ_${uppercased}` as PermissionString,
+    create: `CREATE_${uppercased}` as PermissionString,
+    update: `UPDATE_${uppercased}` as PermissionString,
+    delete: `DELETE_${uppercased}` as PermissionString,
+  };
+};
+
+// Usage
+const assetPerms = getEntityPermissions('assets');
+// { read: 'READ_ASSETS', create: 'CREATE_ASSETS', ... }
+```
+
+---
+
+### 4. Runtime Types (`runtime.ts`)
+
+Types for runtime presentation playback.
+
+#### RuntimeProject
+```typescript
+export interface RuntimeProject {
+  id: string;
+  name?: string;
+  slug?: string;
+  description?: string;
+}
+```
+
+#### RuntimePage
+```typescript
+// Extends PreloadPage with display/navigation fields
+export interface RuntimePage extends PreloadPage {
+  slug?: string;
+  name?: string;
+  sort_order?: number;
+  ui_schema_json?: string;
+  environment?: 'dev' | 'stage' | 'production';
+  // Background video playback settings
+  background_video_autoplay?: boolean;
+  background_video_loop?: boolean;
+  background_video_muted?: boolean;
+  background_video_start_time?: number | null;
+  background_video_end_time?: number | null;
+  // Background audio playback settings
+  background_audio_autoplay?: boolean;
+  background_audio_loop?: boolean;
+  background_audio_start_time?: number | null;
+  background_audio_end_time?: number | null;
+  // Design canvas dimensions (copied from project on save)
+  design_width?: number | null;
+  design_height?: number | null;
+}
+```
+
+#### RuntimeTransition
+```typescript
+export interface RuntimeTransition {
+  id: string;
+  name?: string;
+  slug?: string;
+  video_url?: string;
+  duration_sec?: number;
+  supports_reverse?: boolean;
+}
+```
+
+#### TransitionOverlayState
+```typescript
+export interface TransitionOverlayState {
+  targetPageId: string;
+  transitionName: string;
+  videoUrl: string;
+  isReverse: boolean;
+  durationSec?: number;
+}
+```
+
+#### Global UI Control Types (`uiControls.ts`)
+
+Global UI-control types describe the fullscreen, sound, and offline system
+buttons and their cascade:
+
+```typescript
+export type SystemUiControlType = 'fullscreen' | 'sound' | 'offline';
+export type SystemUiControlAnchor =
+  | 'center'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right';
+
+export interface SystemUiControlSettings {
+  enabled?: boolean;
+  hidden?: boolean;
+  xPercent?: number;
+  yPercent?: number;
+  anchor?: SystemUiControlAnchor;
+  buttonSizePercent?: number;
+  iconSizePercent?: number;
+  defaultIconUrl?: string;
+  activeIconUrl?: string;
+  defaultBackgroundColor?: string;
+  activeBackgroundColor?: string;
+  defaultBorderColor?: string;
+  activeBorderColor?: string;
+}
+```
+
+Helpers:
+- `resolveUiControlsSettings(global, project, page)` merges the cascade
+  field-by-field.
+- `parseUiControlsSettings(value)` normalizes JSON/string input.
+- `getSystemControlAnchorBounds(anchor, size, aspectRatio)` clamps controls
+  inside the visible canvas.
+
+---
+
+### 5. Presentation Types (`presentation.ts`)
+
+Shared types for `RuntimePresentation` and `constructor.tsx`.
+
+**Note:** Not exported from `index.ts`, must import directly from `@/types/presentation`.
+
+#### Navigation Types
+```typescript
+export interface NavigableElement {
+  id: string;
+  type: string;
+  targetPageSlug?: string;
+  targetPageId?: string;
+  transitionVideoUrl?: string;
+  navType?: 'forward' | 'back';
+  navDisabled?: boolean;
+}
+
+export interface NavigationTarget {
+  page: RuntimePage;
+  pageId: string;
+  transitionVideoUrl?: string;
+  isBack: boolean;
+}
+```
+
+#### RuntimeProject (Presentation)
+```typescript
+// Duplicate definition for page data loader context
+export interface RuntimeProject {
+  id: string;
+  name?: string;
+  slug?: string;
+  description?: string;
+}
+```
+
+#### Transition Phase
+```typescript
+export type TransitionPhase =
+  | 'idle'       // No transition
+  | 'preparing'  // Loading video
+  | 'playing'    // Forward playback
+  | 'reversing'  // Reverse playback
+  | 'completed'; // Finished
+```
+
+#### Background State
+```typescript
+export interface BackgroundState {
+  imageUrl: string;
+  videoUrl: string;
+  audioUrl: string;
+}
+
+export interface TransitionPreviewState {
+  targetPageId: string;
+  videoUrl: string;
+  storageKey: string;
+  isReverse: boolean;
+}
+```
+
+#### Page Data Loader
+```typescript
+export interface PageDataLoaderResult {
+  project: RuntimeProject | null;
+  pages: RuntimePage[];
+  isLoading: boolean;
+  error: string;
+  reload: (preservePageId?: string) => Promise<void>;
+}
+```
+
+#### Runtime API Config
+```typescript
+export interface RuntimeApiConfig {
+  headers: {
+    'X-Runtime-Project-Slug'?: string;
+    'X-Runtime-Environment'?: string;
+  };
+}
+```
+
+#### Background Transition Options
+```typescript
+export interface BackgroundTransitionOptions {
+  pendingTransitionComplete: boolean;
+  isBackgroundReady: boolean;
+  transitionVideoRef: React.RefObject<HTMLVideoElement | null>;
+  pageSwitch: {
+    clearPreviousBackground: () => void;
+    isSwitching: boolean;
+    isNewBgReady: boolean;
+    previousBgImageUrl: string;
+  };
+  onCleanup: () => void;
+}
+```
+
+---
+
+### 6. Preload Types (`preload.ts`)
+
+Minimal types for asset preloading infrastructure.
+
+#### PreloadPage
+```typescript
+// Simplified page type (subset of TourPage)
+export interface PreloadPage {
+  id: string;
+  background_image_url?: string;
+  background_video_url?: string;
+  background_audio_url?: string;
+}
+```
+
+#### PreloadPageLink
+```typescript
+export interface PreloadPageLink {
+  id: string;
+  from_pageId?: string;
+  to_pageId?: string;
+  is_active?: boolean;
+  transition?: {
+    id: string;
+    video_url?: string;
+  };
+}
+```
+
+#### PreloadElement
+```typescript
+export interface PreloadElement {
+  id: string;
+  pageId?: string;
+  element_type?: string;
+  content_json?: string;
+}
+```
+
+#### PreloadAssetInfo
+```typescript
+export interface PreloadAssetInfo {
+  url: string;
+  pageId: string;
+  assetType: 'image' | 'video' | 'audio' | 'transition' | 'other';
+  priority: number;
+}
+```
+
+#### PreloadNeighborInfo
+```typescript
+export interface PreloadNeighborInfo {
+  pageId: string;
+  distance: number;
+}
+```
+
+---
+
+### 7. Offline Types (`offline.ts`)
+
+Types for PWA and offline storage functionality.
+
+#### Asset Variant & Type
+```typescript
+export type AssetVariantType =
+  | 'thumbnail' | 'preview' | 'webp'
+  | 'mp4_low' | 'mp4_high' | 'original';
+
+export type AssetType = 'image' | 'video' | 'audio' | 'transition' | 'other';
+```
+
+#### Preload Job
+```typescript
+export type PreloadJobStatus =
+  | 'queued' | 'downloading' | 'completed' | 'error' | 'paused';
+
+export interface PreloadJob {
+  id: string;
+  assetId: string;
+  url: string;
+  filename: string;
+  progress: number;
+  status: PreloadJobStatus;
+  bytesLoaded: number;
+  totalBytes: number;
+  pageId?: string;
+  variantType?: AssetVariantType;
+  assetType?: AssetType;
+  error?: string;
+  addedAt: number;
+  startedAt?: number;
+  completedAt?: number;
+}
+```
+
+#### Offline Project
+```typescript
+export type ProjectOfflineStatus =
+  | 'not_downloaded' | 'downloading' | 'downloaded' | 'outdated' | 'error';
+
+export interface OfflineProject {
+  id: string;
+  slug: string;
+  name: string;
+  status: ProjectOfflineStatus;
+  totalAssets: number;
+  downloadedAssets: number;
+  totalSizeBytes: number;
+  downloadedSizeBytes: number;
+  lastSyncedAt?: number;
+  version?: string;
+}
+```
+
+#### Offline Asset (IndexedDB)
+```typescript
+export interface OfflineAsset {
+  id: string;
+  projectId: string;
+  url: string;
+  filename: string;
+  variantType: AssetVariantType;
+  assetType: AssetType;
+  mimeType: string;
+  sizeBytes: number;
+  blob: Blob;
+  downloadedAt: number;
+}
+```
+
+#### Download Queue Item
+```typescript
+export interface DownloadQueueItem {
+  id: string;
+  projectId: string;
+  assetId: string;
+  url: string;
+  filename: string;
+  status: PreloadJobStatus;
+  priority: number;
+  retryCount: number;
+  bytesLoaded: number;
+  totalBytes: number;
+  addedAt: number;
+  lastAttemptAt?: number;
+  error?: string;
+}
+```
+
+#### Network & Storage Info
+```typescript
+export interface NetworkInfo {
+  isOnline: boolean;
+  effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
+  downlink?: number; // Mbps
+  rtt?: number;      // ms
+  saveData?: boolean;
+}
+
+export interface StorageQuotaInfo {
+  usage: number;
+  quota: number;
+  percentUsed: number;
+  available: number;
+  canStore: (bytes: number) => boolean;
+}
+```
+
+#### Offline Manifest
+```typescript
+export interface OfflineManifest {
+  version: string;
+  projectId: string;
+  projectSlug: string;
+  assets: ManifestAsset[];
+  totalSizeBytes: number;
+  generatedAt: number;
+}
+
+export interface ManifestAsset {
+  id: string;
+  url: string;
+  filename: string;
+  variantType: AssetVariantType;
+  assetType: AssetType;
+  mimeType: string;
+  sizeBytes: number;
+  pageIds: string[];
+}
+```
+
+#### Preload State & Neighbor Graph
+```typescript
+export interface PreloadState {
+  isActive: boolean;
+  currentPageId: string | null;
+  queuedAssets: string[];
+  loadingAssets: string[];
+  completedAssets: string[];
+  failedAssets: string[];
+  totalProgress: number;
+}
+
+export interface NeighborGraph {
+  connections: Map<string, Array<{ pageId: string; distance: number }>>;
+  getNeighbors: (pageId: string, maxDepth: number) => string[];
+  getAssetsForPages: (pageIds: string[]) => string[];
+}
+```
+
+#### Event Payloads
+```typescript
+export interface PreloadStartEvent {
+  jobId: string;
+  assetId: string;
+  url: string;
+}
+
+export interface PreloadProgressEvent {
+  jobId: string;
+  progress: number;
+  bytesLoaded: number;
+  totalBytes: number;
+}
+
+export interface PreloadCompleteEvent {
+  jobId: string;
+  assetId: string;
+}
+
+export interface PreloadErrorEvent {
+  jobId: string;
+  assetId: string;
+  error: string;
+}
+
+export interface ProjectDownloadProgressEvent {
+  projectId: string;
+  progress: number;
+  downloadedAssets: number;
+  totalAssets: number;
+  downloadedBytes: number;
+  totalBytes: number;
+}
+
+export interface ProjectDownloadCompleteEvent {
+  projectId: string;
+}
+```
+
+---
+
+### 8. API Types (`api.ts`)
+
+Types for API requests and responses.
+
+#### Paginated Response
+```typescript
+export interface PaginatedResponse<T> {
+  rows: T[];
+  count: number;
+}
+```
+
+#### Fetch Parameters
+```typescript
+export interface FetchParams {
+  id?: string;
+  query?: string;
+  limit?: number;
+  page?: number;
+}
+```
+
+#### List Query Parameters
+```typescript
+export interface ListQueryParams {
+  page?: number;
+  limit?: number;
+  sort?: 'asc' | 'desc';
+  field?: string;
+  [filterKey: string]: string | number | boolean | undefined;
+}
+```
+
+#### Sort Model & Autocomplete
+```typescript
+export interface SortModel {
+  field: string;
+  sort: 'asc' | 'desc';
+}
+
+export interface AutocompleteItem {
+  id: string;
+  label: string;
+}
+```
+
+#### API Error
+```typescript
+export interface ApiError {
+  message?: string;
+  statusCode?: number;
+  errors?: Record<string, { _errors: string[] }>;
+}
+```
+
+#### Mutation Payloads
+```typescript
+export interface MutationPayload<T> {
+  id?: string;
+  data: Partial<T>;
+}
+
+export interface DeleteByIdsPayload {
+  ids: string[];
+}
+
+export interface CsvUploadResponse {
+  imported: number;
+  errors?: string[];
+}
+```
+
+---
+
+### 9. Redux Types (`redux.ts`)
+
+Types for Redux state management.
+
+#### Notification State
+```typescript
+export interface NotificationState {
+  showNotification: boolean;
+  textNotification: string;
+  typeNotification: 'warn' | 'error' | 'success' | 'info' | '';
+}
+```
+
+#### Entity Slice State
+```typescript
+export interface EntitySliceState<T> {
+  data: T[];
+  loading: boolean;
+  count: number;
+  refetch: boolean;
+  notify: NotificationState;
+}
+```
+
+#### Slice Factory Config
+```typescript
+export interface EntitySliceConfig {
+  name: string;
+  endpoint: string;
+  singularName?: string; // For notification messages
+}
+```
+
+#### Core State Types
+```typescript
+export interface AuthState {
+  currentUser: User | null;
+  token: string | null;
+  isFetching: boolean;
+  errorMessage: string | null;
+  loadingMessage: string | null;
+  notify: NotificationState;
+}
+
+export interface StyleState {
+  darkMode: boolean;
+  bgLayoutColor: string;
+  focusRingColor: string;
+  corners: string;
+  cardsColor: string;
+}
+
+export interface MainState {
+  isAsideMobileExpanded: boolean;
+  isAsideLgActive: boolean;
+}
+```
+
+---
+
+### 10. Forms Types (`forms.ts`)
+
+Types for form rendering and validation.
+
+#### Form Field Types
+```typescript
+export type FormFieldType =
+  | 'text' | 'email' | 'number' | 'password'
+  | 'textarea' | 'richtext'
+  | 'select' | 'multiselect'
+  | 'date' | 'datetime'
+  | 'boolean' | 'switch'
+  | 'image' | 'file' | 'enum';
+```
+
+#### Form Field Config
+```typescript
+export interface FormFieldConfig {
+  name: string;
+  label: string;
+  type: FormFieldType;
+  required?: boolean;
+  placeholder?: string;
+  itemRef?: string;      // Entity endpoint for options
+  showField?: string;    // Display field from options
+  options?: EnumOption[];
+  uploadPath?: string;
+  fileSchema?: FileSchema;
+  min?: number;
+  max?: number;
+  maxLength?: number;
+  className?: string;
+}
+```
+
+#### Form Page Config
+```typescript
+export interface FormPageConfig<TFormData> {
+  entityName: string;
+  entityTitle: string;
+  mode: 'create' | 'edit';
+  permission: string;
+  initialValues: TFormData;
+  fields: FormFieldConfig[];
+  listPath?: string;
+}
+```
+
+---
+
+### 11. Filters Types (`filters.ts`)
+
+Types for table filtering and sorting.
+
+#### Filter Definition
+```typescript
+export type FilterType = 'text' | 'enum' | 'date' | 'number' | 'boolean';
+
+export interface Filter {
+  label: string;
+  title: string; // Field name to filter by
+  type?: FilterType;
+  options?: string[]; // For enum filters
+  number?: boolean;
+  date?: boolean;
+}
+```
+
+#### Active Filter
+```typescript
+export interface FilterItem {
+  id: string;
+  fields: FilterFields;
+}
+
+export interface FilterFields {
+  selectedField: string;
+  filterValue: string;
+  filterValueFrom: string;
+  filterValueTo: string;
+}
+```
+
+#### Table Configuration
+```typescript
+export interface TableColumnConfig {
+  field: string;
+  headerName: string;
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  flex?: number;
+  editable?: boolean;
+  sortable?: boolean;
+  filterable?: boolean;
+  type?: 'string' | 'number' | 'date' | 'dateTime' | 'boolean' | 'singleSelect';
+  valueOptions?: string[];
+  renderType?: 'link' | 'boolean' | 'date' | 'datetime' | 'image' | 'actions' | 'relation';
+  relationField?: string;
+}
+
+export interface TableConfig {
+  entityName: string;
+  columns: TableColumnConfig[];
+  filters: Filter[];
+  defaultSort?: { field: string; sort: 'asc' | 'desc' };
+  perPage?: number;
+}
+```
+
+---
+
+### 12. Specialized Types
+
+Additional type files for specific features.
+
+#### Charts Types (`charts.ts`)
+```typescript
+export interface ChartDataPoint {
+  label: string;
+  value: number;
+}
+
+export interface DashboardStats {
+  totalProjects: number;
+  totalPages: number;
+  totalAssets: number;
+  recentActivity: ActivityItem[];
+}
+```
+
+#### Components Types (`components.ts`)
+```typescript
+export interface BaseComponentProps {
+  className?: string;
+  children?: React.ReactNode;
+}
+
+export interface DataGridProps<T> {
+  rows: T[];
+  columns: GridColDef[];
+  loading?: boolean;
+}
+```
+
+#### Menu Types (`menu.ts`)
+```typescript
+export interface MenuItem {
+  label: string;
+  href?: string;
+  icon?: string;
+  permission?: string;
+  children?: MenuItem[];
+}
+```
+
+#### UI Types (`ui.ts`)
+```typescript
+export interface ToastNotification {
+  id: string;
+  type: 'success' | 'error' | 'info' | 'warning';
+  message: string;
+  duration?: number;
+}
+
+export interface ModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  title?: string;
+}
+```
+
+---
+
+## Type Relationships
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      entities.ts                            │
+│  BaseEntity → User, Project, Asset, TourPage, etc.         │
+└─────────────────────────────────────────────────────────────┘
+              │
+              ├──────────────────────────────┐
+              ▼                              ▼
+┌─────────────────────────┐    ┌─────────────────────────────┐
+│    constructor.ts       │    │       runtime.ts            │
+│                         │    │                             │
+│ CanvasElement           │    │ RuntimePage extends         │
+│ (extends styles/effects)│    │ PreloadPage                 │
+└─────────────────────────┘    └─────────────────────────────┘
+              │                              │
+              ▼                              ▼
+┌─────────────────────────┐    ┌─────────────────────────────┐
+│   presentation.ts       │    │      preload.ts             │
+│                         │    │                             │
+│ NavigableElement        │◄───│ PreloadPage                 │
+│ NavigationTarget        │    │ PreloadPageLink             │
+│ TransitionPhase         │    │ PreloadElement              │
+└─────────────────────────┘    └─────────────────────────────┘
+                                             │
+                                             ▼
+                               ┌─────────────────────────────┐
+                               │      offline.ts             │
+                               │                             │
+                               │ OfflineAsset                │
+                               │ DownloadQueueItem           │
+                               │ PreloadJob                  │
+                               └─────────────────────────────┘
+```
+
+---
+
+## Import Patterns
+
+### Central Import (Recommended)
+```typescript
+// Import from central index (10 modules re-exported)
+// entities, api, redux, forms, filters, permissions,
+// offline, preload, runtime, constructor
+import type {
+  User,
+  Project,
+  Asset,
+  CanvasElement,
+  Permission,
+  PaginatedResponse,
+} from '@/types';
+```
+
+### Direct Import (For Specific Modules)
+```typescript
+// Import from specific file
+import type { CanvasElement, CanvasElementType } from '@/types/constructor';
+import type { RuntimePage, RuntimeProject } from '@/types/runtime';
+import type { PreloadJob, OfflineAsset } from '@/types/offline';
+
+// Note: presentation.ts is NOT exported from index.ts, must import directly
+import type { NavigableElement, TransitionPhase } from '@/types/presentation';
+```
+
+---
+
+## Usage Examples
+
+### Entity Types in API Calls
+```typescript
+import type { User, PaginatedResponse } from '@/types';
+
+const response = await axios.get<PaginatedResponse<User>>('/api/users');
+const users: User[] = response.data.rows;
+```
+
+### Canvas Elements in Constructor
+```typescript
+import type { CanvasElement, CanvasElementType } from '@/types/constructor';
+import { isCanvasElementType } from '@/types/constructor';
+
+const handleAddElement = (type: string) => {
+  if (isCanvasElementType(type)) {
+    const element: CanvasElement = createDefaultElement(type);
+    setElements([...elements, element]);
+  }
+};
+```
+
+### Permissions in Components
+```typescript
+import { Permission } from '@/types/permissions';
+
+const canEdit = userPermissions.includes(Permission.UPDATE_PROJECTS);
+```
+
+### Redux State Types
+```typescript
+import type { EntitySliceState, NotificationState } from '@/types/redux';
+
+interface UsersSliceState extends EntitySliceState<User> {
+  // Additional state if needed
+}
+```
+
+### Offline Storage Types
+```typescript
+import type { OfflineAsset, PreloadJobStatus } from '@/types/offline';
+
+const asset: OfflineAsset = {
+  id: 'asset-1',
+  projectId: 'project-1',
+  url: 'https://...',
+  filename: 'image.jpg',
+  variantType: 'original',
+  assetType: 'image',
+  mimeType: 'image/jpeg',
+  sizeBytes: 1024000,
+  blob: imageBlob,
+  downloadedAt: Date.now(),
+};
+```
+
+---
+
+## Best Practices
+
+### 1. Use Type Guards
+```typescript
+// Use type guards for runtime type checking
+if (isCanvasElementType(element.type)) {
+  // TypeScript knows type is CanvasElementType
+}
+```
+
+### 2. Prefer Interfaces for Objects
+```typescript
+// Good - interfaces are extendable
+export interface User extends BaseEntity { ... }
+
+// Use types for unions/primitives
+export type CanvasElementType = 'navigation_next' | 'navigation_prev' | ...
+```
+
+### 3. Use Generic Types
+```typescript
+// Generic response types
+export interface PaginatedResponse<T> {
+  rows: T[];
+  count: number;
+}
+
+// Usage
+const response: PaginatedResponse<Asset>;
+```
+
+### 4. Document Deprecations
+```typescript
+export interface CanvasElement {
+  /** @deprecated Use targetPageSlug instead - IDs change when copied */
+  targetPageId?: string;
+  targetPageSlug?: string;
+}
+```
+
+### 5. Export via Index
+```typescript
+// types/index.ts
+export * from './entities';
+export * from './api';
+// ... all modules
+
+// Consumer
+import type { User, Asset, Permission } from '@/types';
+```
+
+---
+
+## Related Documentation
+
+- [entities.ts Definitions](./stores-module.md#entity-types) - Used in Redux slices
+- [constructor.ts Usage](./constructor-page-editor.md) - Constructor page documentation
+- [lib-module.md](./lib-module.md) - Element styles/effects types from lib
+- [hooks-module.md](./hooks-module.md) - Hooks using these types
+- [stores-module.md](./stores-module.md) - Redux state types
diff --git a/frontend/docs/ui-adaptivity-system.md b/frontend/docs/ui-adaptivity-system.md
new file mode 100644
index 0000000..31fbcb8
--- /dev/null
+++ b/frontend/docs/ui-adaptivity-system.md
@@ -0,0 +1,489 @@
+# UI Adaptivity System
+
+Comprehensive documentation for the Tour Builder Platform's responsive canvas scaling and UI adaptivity system.
+
+## Overview
+
+The platform uses a **Canvas Units** system to ensure UI elements scale proportionally across all viewport sizes while maintaining a consistent design. This system allows content authored at a design resolution (e.g., 1920×1080) to display correctly on any screen size.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    UI Adaptivity Architecture                            │
+│                                                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │                    Configuration Layer                            │  │
+│  │                                                                   │  │
+│  │   canvas.config.ts                                                │  │
+│  │   ├── defaults: { width: 1920, height: 1080 }                    │  │
+│  │   ├── scaling: { mode: 'fit', minScale: 0.1, maxScale: 4.0 }     │  │
+│  │   └── cssVars: { scale: '--canvas-scale', unit: '--cu', ... }    │  │
+│  └───────────────────────────┬──────────────────────────────────────┘  │
+│                              │                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │                     Calculation Layer                             │  │
+│  │                                                                   │  │
+│  │   canvasScale.ts (utilities)                                      │  │
+│  │   ├── calculateCanvasScale(viewport, design) → scale factor      │  │
+│  │   ├── toCU(designPixels) → "calc(N * var(--cu, 1px))"            │  │
+│  │   ├── normalizeToCanvasUnits(value) → canvas unit expression     │  │
+│  │   └── getCanvasCssVars(scale) → CSS custom properties object     │  │
+│  └───────────────────────────┬──────────────────────────────────────┘  │
+│                              │                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │                      Hook/Context Layer                           │  │
+│  │                                                                   │  │
+│  │   useCanvasScale (hook)    │    CanvasScaleContext (context)     │  │
+│  │   ├── scale               │    ├── Same properties               │  │
+│  │   ├── cssVars             │    ├── Provider pattern              │  │
+│  │   ├── letterboxStyles     │    └── Optional hook variant         │  │
+│  │   └── showRotatePrompt    │                                      │  │
+│  └───────────────────────────┬──────────────────────────────────────┘  │
+│                              │                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐  │
+│  │                     Application Layer                             │  │
+│  │                                                                   │  │
+│  │   RuntimePresentation     │    Constructor                        │  │
+│  │   ├── cssVars on root     │    ├── cssVars on canvas             │  │
+│  │   ├── letterboxStyles     │    ├── letterboxStyles               │  │
+│  │   └── Elements use --cu   │    └── Elements use --cu             │  │
+│  └──────────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Core Concepts
+
+### Canvas Units (--cu)
+
+The `--cu` CSS custom property is the foundation of the adaptivity system. It represents "1 design pixel" that scales with the viewport.
+
+```
+At design resolution (1920×1080 on 1920×1080 viewport):
+  --cu = 1px
+
+At 4K (1920×1080 on 3840×2160 viewport):
+  --cu = 2px (elements render 2x larger)
+
+At half-resolution (1920×1080 on 960×540 viewport):
+  --cu = 0.5px (elements render at half size)
+```
+
+**Usage:**
+```css
+/* Direct CSS usage */
+.element {
+  font-size: calc(24 * var(--cu, 1px));  /* 24px at design scale */
+  padding: calc(16 * var(--cu, 1px));
+  border-radius: calc(8 * var(--cu, 1px));
+}
+```
+
+```typescript
+// JavaScript usage via toCU()
+import { toCU } from '../lib/canvasScale';
+
+const style = {
+  fontSize: toCU(24),      // "calc(24 * var(--cu, 1px))"
+  padding: toCU(16),       // "calc(16 * var(--cu, 1px))"
+  borderRadius: toCU(8),   // "calc(8 * var(--cu, 1px))"
+};
+```
+
+### Scale Factor Calculation
+
+The scale factor is calculated to fit the design canvas within the viewport while maintaining aspect ratio:
+
+```typescript
+// canvasScale.ts
+export function calculateCanvasScale(
+  viewportWidth: number,
+  viewportHeight: number,
+  designWidth: number = 1920,
+  designHeight: number = 1080,
+): number {
+  const scaleX = viewportWidth / designWidth;
+  const scaleY = viewportHeight / designHeight;
+
+  // Use min() to fit content within viewport (letterbox/pillarbox)
+  const scale = Math.min(scaleX, scaleY);
+
+  // Clamp to configured min/max (0.1 - 4.0)
+  return Math.max(0.1, Math.min(4.0, scale));
+}
+```
+
+### Letterbox Mode
+
+When the viewport aspect ratio doesn't match the design aspect ratio, the system creates black bars (letterbox for horizontal bars, pillarbox for vertical bars) to maintain content proportions.
+
+```typescript
+// Generated letterbox styles
+const letterboxStyles: CSSProperties = {
+  width: designWidth * scale,      // Actual canvas width
+  height: designHeight * scale,    // Actual canvas height
+  position: 'absolute',
+  left: '50%',
+  top: '50%',
+  transform: 'translate(-50%, -50%)',  // Center in viewport
+};
+```
+
+**Visual Example:**
+```
+┌─────────────────────────────────────────┐
+│░░░░░░░░░░░░░ Letterbox Bar ░░░░░░░░░░░░│  ← Black bar (wider viewport)
+├─────────────────────────────────────────┤
+│                                         │
+│              Canvas Content             │  ← Design content (1920×1080)
+│           (maintains 16:9 ratio)        │
+│                                         │
+├─────────────────────────────────────────┤
+│░░░░░░░░░░░░░ Letterbox Bar ░░░░░░░░░░░░│  ← Black bar
+└─────────────────────────────────────────┘
+```
+
+### Global UI Controls
+
+Fullscreen, global sound, and offline controls are positioned against the same
+visible canvas rectangle as page elements. Their coordinates are stored as
+`xPercent`/`yPercent`. Their dimensions are stored as canvas-width-relative
+percentages (`buttonSizePercent`, `iconSizePercent`,
+`borderRadiusPercent`), so they scale with the displayed canvas instead of
+remaining fixed CSS pixels.
+
+Vertical clamping accounts for the canvas aspect ratio because button height is
+also derived from canvas width. This keeps controls fully inside the canvas for
+16:9, 4:3, ultra-wide, and custom project ratios.
+
+## File Reference
+
+### Configuration
+
+**File:** `frontend/src/config/canvas.config.ts`
+
+```typescript
+export const CANVAS_CONFIG = {
+  // Default design dimensions
+  defaults: {
+    width: 1920,
+    height: 1080,
+  },
+
+  // Common presets for project settings
+  presets: [
+    { name: 'HD 16:9', width: 1920, height: 1080 },
+    { name: '4K 16:9', width: 3840, height: 2160 },
+    { name: 'HD 4:3', width: 1440, height: 1080 },
+    { name: 'Ultra-wide 21:9', width: 2560, height: 1080 },
+  ],
+
+  // Scaling behavior
+  scaling: {
+    mode: 'fit' as const,  // Fit within viewport, may letterbox
+    minScale: 0.1,
+    maxScale: 4.0,
+  },
+
+  // Portrait orientation handling
+  orientation: {
+    showRotatePrompt: true,
+    minAspectRatioForPrompt: 0.8,
+  },
+
+  // CSS custom property names
+  cssVars: {
+    scale: '--canvas-scale',
+    unit: '--cu',
+    designWidth: '--design-width',
+    designHeight: '--design-height',
+  },
+};
+```
+
+### Utilities
+
+**File:** `frontend/src/lib/canvasScale.ts`
+
+| Function | Purpose |
+|----------|---------|
+| `calculateCanvasScale(vw, vh, dw, dh)` | Calculate scale factor for viewport |
+| `toCU(designPixels)` | Convert design pixels to `calc()` expression |
+| `isLegacyUnit(value)` | Check if value uses px/rem/vw/vh units |
+| `normalizeToCanvasUnits(value, property)` | Convert legacy units to canvas units |
+| `getCanvasCssVars(scale, dw, dh)` | Generate CSS custom properties object |
+| `vwToDesignPx(vw)` | Convert viewport width to design pixels |
+| `vhToDesignPx(vh)` | Convert viewport height to design pixels |
+| `remToDesignPx(rem)` | Convert rem to design pixels (16px base) |
+
+### Hook
+
+**File:** `frontend/src/hooks/useCanvasScale.ts`
+
+```typescript
+interface UseCanvasScaleOptions {
+  designWidth?: number;   // From project.design_width
+  designHeight?: number;  // From project.design_height
+}
+
+interface CanvasScaleResult {
+  scale: number;                    // Current scale factor (1.0 = design size)
+  designWidth: number;              // Design canvas width
+  designHeight: number;             // Design canvas height
+  canvasWidth: number;              // Calculated width at current scale
+  canvasHeight: number;             // Calculated height at current scale
+  isPortrait: boolean;              // Viewport is portrait orientation
+  showRotatePrompt: boolean;        // Should show "rotate device" prompt
+  cssVars: CSSProperties;           // CSS custom properties object
+  letterboxStyles: CSSProperties;   // Styles for letterbox container
+}
+
+// Usage
+const {
+  scale,
+  cssVars,
+  letterboxStyles,
+  isPortrait,
+  showRotatePrompt,
+} = useCanvasScale({
+  designWidth: project.design_width,
+  designHeight: project.design_height,
+});
+```
+
+### Context (Optional)
+
+**File:** `frontend/src/context/CanvasScaleContext.tsx`
+
+For deeply nested components that need access to canvas scale without prop drilling:
+
+```typescript
+// Provider setup
+<CanvasScaleProvider
+  designWidth={project.design_width}
+  designHeight={project.design_height}
+>
+  {children}
+</CanvasScaleProvider>
+
+// Consumer hook
+const { scale, cssVars } = useCanvasScaleContext();
+
+// Optional variant (returns null if no provider)
+const scaleContext = useCanvasScaleContextOptional();
+```
+
+## Element Styling Integration
+
+### elementStyles.ts
+
+**File:** `frontend/src/lib/elementStyles.ts`
+
+The element styles library automatically converts values to canvas units:
+
+```typescript
+// Normalization functions
+normalizePixelValue('24')      // → "calc(24 * var(--cu, 1px))"
+normalizePixelValue('24px')    // → "calc(24 * var(--cu, 1px))"
+normalizeViewportWidth('50vw') // → "calc(960 * var(--cu, 1px))" (50% of 1920)
+normalizeViewportHeight('25vh')// → "calc(270 * var(--cu, 1px))" (25% of 1080)
+
+// Build complete style object
+const style = buildElementStyle({
+  width: '200',
+  height: '100',
+  fontSize: '16',
+  borderRadius: '8',
+});
+// Result: all values converted to calc() expressions with --cu
+```
+
+### useElementWrapperStyle Hook
+
+**File:** `frontend/src/components/UiElements/shared/useElementWrapperStyle.ts`
+
+Provides consistent styling for UI elements across constructor and runtime:
+
+```typescript
+const { className, style } = useElementWrapperStyle({
+  element,
+  isSelected: false,
+  isEditMode: false,
+});
+
+// Returns:
+// - className: Tailwind classes for appearance
+// - style: CSSProperties with canvas unit values
+```
+
+## Usage Patterns
+
+### RuntimePresentation
+
+```typescript
+// RuntimePresentation.tsx
+const { cssVars, letterboxStyles } = useCanvasScale({
+  designWidth: project.design_width,
+  designHeight: project.design_height,
+});
+
+return (
+  <div className="relative w-screen h-screen overflow-hidden bg-black">
+    {/* Inner canvas: maintains aspect ratio */}
+    <div
+      className="overflow-hidden"
+      style={{
+        ...cssVars,           // Sets --cu, --canvas-scale, etc.
+        ...letterboxStyles,   // Centers and sizes canvas
+      }}
+    >
+      {/* All child elements use --cu for sizing */}
+      {elements.map(el => <RuntimeElement key={el.id} element={el} />)}
+    </div>
+  </div>
+);
+```
+
+### Constructor
+
+```typescript
+// constructor.tsx
+const { cssVars, letterboxStyles } = useCanvasScale({
+  designWidth: project?.design_width,
+  designHeight: project?.design_height,
+});
+
+return (
+  <div
+    className="overflow-hidden"
+    style={{
+      ...cssVars,
+      ...letterboxStyles,
+    }}
+  >
+    <CanvasBackground ... />
+    <div className="absolute inset-0 z-10">
+      {elements.map(el => <CanvasElement key={el.id} element={el} />)}
+    </div>
+  </div>
+);
+```
+
+### Individual Elements
+
+```typescript
+// Element component using canvas units
+import { toCU } from '../../lib/canvasScale';
+
+const ButtonElement = ({ element }) => {
+  return (
+    <button
+      style={{
+        fontSize: toCU(element.fontSize || 16),
+        padding: `${toCU(8)} ${toCU(16)}`,
+        borderRadius: toCU(element.borderRadius || 4),
+      }}
+    >
+      {element.label}
+    </button>
+  );
+};
+```
+
+## CSS Custom Properties
+
+The system sets these CSS custom properties on the canvas container:
+
+| Property | Description | Example Value |
+|----------|-------------|---------------|
+| `--cu` | Canvas unit (1 design pixel) | `calc(1px * 0.75)` |
+| `--canvas-scale` | Current scale factor | `0.75` |
+| `--design-width` | Design canvas width | `1920` |
+| `--design-height` | Design canvas height | `1080` |
+
+**CSS Usage:**
+```css
+.element {
+  /* Use --cu for scalable dimensions */
+  font-size: calc(18 * var(--cu, 1px));
+
+  /* Use --canvas-scale for transforms */
+  transform: scale(var(--canvas-scale, 1));
+
+  /* Use design dimensions for calculations */
+  width: calc(var(--design-width) * 0.5 * var(--cu, 1px));
+}
+```
+
+## Legacy Unit Migration
+
+When encountering legacy units (px, vw, vh, rem), use the normalization utilities:
+
+```typescript
+import { normalizeToCanvasUnits } from '../lib/canvasScale';
+
+// Convert various legacy formats
+normalizeToCanvasUnits('24px', 'fontSize');     // → "calc(24 * var(--cu, 1px))"
+normalizeToCanvasUnits('50vw', 'width');        // → "calc(960 * var(--cu, 1px))"
+normalizeToCanvasUnits('25vh', 'height');       // → "calc(270 * var(--cu, 1px))"
+normalizeToCanvasUnits('1.5rem', 'fontSize');   // → "calc(24 * var(--cu, 1px))"
+normalizeToCanvasUnits(100, 'width');           // → "calc(100 * var(--cu, 1px))"
+```
+
+## Orientation Handling
+
+The system detects portrait orientation and can prompt users to rotate their device:
+
+```typescript
+const { isPortrait, showRotatePrompt } = useCanvasScale({
+  designWidth: 1920,
+  designHeight: 1080,
+});
+
+// showRotatePrompt is true when:
+// 1. Device is in portrait mode (height > width)
+// 2. orientation.showRotatePrompt is enabled in config
+// 3. Aspect ratio < minAspectRatioForPrompt (0.8)
+
+{showRotatePrompt && (
+  <RotateDeviceOverlay />
+)}
+```
+
+## Integration Points
+
+| Component | Uses | Purpose |
+|-----------|------|---------|
+| `RuntimePresentation` | `useCanvasScale` | Full-screen tour playback |
+| `constructor.tsx` | `useCanvasScale` | Tour editing canvas |
+| `TransitionPreviewOverlay` | `letterboxStyles` prop | Transition videos within canvas |
+| `CanvasBackground` | Inherits from parent | Background media display |
+| `RuntimeElement` | `buildElementStyle` | Element rendering |
+| `CanvasElement` | `useElementWrapperStyle` | Element editing |
+| `CarouselElement` | `toCU()` | Gallery styling |
+| `gallerySectionStyles` | `toCU()` | Gallery section dimensions |
+
+## Performance Considerations
+
+1. **Resize listener** - Uses single `resize` event listener, debounced via React state
+2. **Memoization** - Scale calculations wrapped in `useMemo` to prevent recalculation
+3. **CSS calc()** - Browser handles scaling efficiently via CSS custom properties
+4. **No layout thrashing** - Scale updates don't trigger element-by-element recalculation
+
+## Troubleshooting
+
+### Elements Not Scaling
+
+1. Verify `cssVars` is applied to a parent container
+2. Check that values use `toCU()` or normalization functions
+3. Ensure `--cu` is not overridden by other styles
+
+### Letterbox Not Appearing
+
+1. Parent container must have `overflow: hidden` and `bg-black`
+2. `letterboxStyles` must be applied to inner container
+3. Check that viewport dimensions are being detected (resize listener)
+
+### Scale Factor Too Small/Large
+
+1. Check `minScale` and `maxScale` in canvas.config.ts
+2. Verify project's `design_width` and `design_height` are set correctly
+3. Test with different viewport sizes to confirm scaling behavior
diff --git a/frontend/docs/ui-element-preloading-analysis.md b/frontend/docs/ui-element-preloading-analysis.md
new file mode 100644
index 0000000..ab02948
--- /dev/null
+++ b/frontend/docs/ui-element-preloading-analysis.md
@@ -0,0 +1,410 @@
+# UI Element Processing & Neighbor Preloading Analysis
+
+## Executive Summary
+
+Deep analysis of how UI elements are processed throughout the Tour Builder Platform - from creation in the Constructor, to rendering in Runtime Presentations, across Online and Offline modes. This document traces each preloading thread step-by-step to verify robustness.
+
+---
+
+## 1. PRELOAD CONFIGURATION (Single Source of Truth)
+
+**File:** `src/config/preload.config.ts`
+
+### 1.1 Asset URL Fields Configuration
+
+```typescript
+assetFields: {
+  // All 18 URL fields for preloading extraction
+  all: [
+    'iconUrl',                    // Base element icon
+    'imageUrl',                   // Generic image reference
+    'mediaUrl',                   // Video/audio player source
+    'videoUrl',                   // Video element
+    'audioUrl',                   // Audio element
+    'transitionVideoUrl',         // Navigation transition video
+    'backgroundImageUrl',         // Element background
+    'reverseVideoUrl',            // Reverse transition video
+    'carouselPrevIconUrl',        // Carousel prev button
+    'carouselNextIconUrl',        // Carousel next button
+    'galleryHeaderImageUrl',      // Gallery header background
+    'galleryCarouselPrevIconUrl', // Gallery carousel prev
+    'galleryCarouselNextIconUrl', // Gallery carousel next
+    'galleryCarouselBackIconUrl', // Gallery carousel back
+    'src', 'url', 'poster', 'thumbnail',  // Generic fallbacks
+  ],
+
+  // 10 Image-only fields for pre-decode optimization
+  images: [
+    'iconUrl', 'imageUrl', 'backgroundImageUrl',
+    'carouselPrevIconUrl', 'carouselNextIconUrl',
+    'galleryHeaderImageUrl', 'galleryCarouselPrevIconUrl',
+    'galleryCarouselNextIconUrl', 'galleryCarouselBackIconUrl', 'src',
+  ],
+
+  // 3 Nested array fields containing assets
+  nested: ['galleryCards', 'carouselSlides', 'galleryInfoSpans'],
+
+  // 3 URL fields within nested items
+  nestedUrlFields: ['imageUrl', 'videoUrl', 'iconUrl'],
+}
+```
+
+### 1.2 Configuration Consumers (10 files)
+
+| File | Uses | Purpose |
+|------|------|---------|
+| `extractPageLinks.ts` | all, nested, nestedUrlFields | Explicit field extraction |
+| `useNeighborGraph.ts` | all | Recursive traversal (depth 5) |
+| `usePreloadOrchestrator.ts` | all | Asset initialization |
+| `imagePreDecode.ts` | images, nested, nestedUrlFields | Image-only pre-decode |
+| `StorageManager.ts` | storage config | Storage thresholds |
+| `DownloadManager.ts` | queue settings | Download concurrency |
+| `useStorageQuota.ts` | storage config | Quota warnings |
+| `usePreloadProgress.ts` | autoRemove | Progress cleanup |
+| `DownloadContext.tsx` | various | Download UI state |
+
+---
+
+## 2. COMPLETE PRELOADING FLOW (Step-by-Step)
+
+### 2.1 Entry Point: RuntimePresentation Mount
+
+```
+RuntimePresentation.tsx mounts
+    ↓
+extractPageLinksAndElements(pages)           [lib/extractPageLinks.ts:105-182]
+    ├── Parse ui_schema_json for each page
+    ├── extractAssetFields(element) → uses PRELOAD_CONFIG.assetFields
+    │   ├── Extract top-level fields from assetFields.all
+    │   └── Extract nested arrays (galleryCards, carouselSlides, galleryInfoSpans)
+    │       └── Within each item, extract nestedUrlFields (imageUrl, videoUrl, iconUrl)
+    ├── Build pageLinks[] for navigation graph
+    └── Build preloadElements[] with content_json containing asset URLs
+    ↓
+usePreloadOrchestrator({ pages, pageLinks, elements, currentPageId })
+```
+
+### 2.2 Thread 1: Neighbor Graph Building
+
+```
+useNeighborGraph({ pages, pageLinks, elements, maxDepth: 1 })
+    ↓
+Build adjacencyList (Map<pageId, neighborPageIds[]>)     [line 119-141]
+    ├── Initialize all pages in map
+    └── Add edges from active pageLinks (from_pageId → to_pageId)
+    ↓
+getNeighbors(currentPageId, depth)                        [line 144-177]
+    ├── BFS traversal from current page
+    ├── Track visited pages to avoid cycles
+    └── Return PreloadNeighborInfo[] sorted by distance
+    ↓
+getAssetsForPages(pageIds)                                [line 180-224]
+    ├── For each page: filter elements by pageId
+    ├── extractAssetsFromContent(content_json)            [line 56-106]
+    │   ├── Parse JSON content
+    │   ├── checkObject() recursive traversal (depth ≤ 5)
+    │   │   └── For each field in PRELOAD_CONFIG.assetFields.all:
+    │   │       └── If string value found, classify asset type and add to assets[]
+    │   └── Return PreloadAssetInfo[] with { url, pageId, assetType, priority }
+    └── Also extract transition videos from pageLinks
+```
+
+### 2.3 Thread 2: Priority Assignment
+
+```
+getPrioritizedAssets(currentPageId, maxDepth)             [line 228-274]
+    ↓
+Current page assets:
+    priority = PRELOAD_CONFIG.priority.currentPage (1000)
+             + PRELOAD_CONFIG.priority.assetType[type]
+
+    Asset type priorities:
+    ├── transition: +150 (highest - needed on navigation click)
+    ├── image: +100 (backgrounds load during transition)
+    ├── audio: +50
+    └── video: +30
+    ↓
+Neighbor page assets:
+    basePriority = PRELOAD_CONFIG.priority.neighborBase (500) / distance
+    priority = basePriority + assetType priority
+    ↓
+Deduplicate by URL, keep highest priority
+Sort descending by priority
+```
+
+### 2.4 Thread 3: URL Resolution (Presigned URLs)
+
+```
+usePreloadOrchestrator effect on currentPageId change     [line 669-924]
+    ↓
+Collect storage paths needing presigning:
+    ├── Current page: background_image_url, background_video_url, background_audio_url
+    ├── Element assets from neighborGraph.getPrioritizedAssets()
+    └── Neighbor pages: background URLs
+    ↓
+queuePresignedUrls(storagePaths)                          [lib/assetUrl.ts]
+    ├── POST /api/file/presign { urls: storagePaths[] }
+    ├── Response: { [storageKey]: presignedUrl }
+    └── Cache presigned URLs (1-hour expiry)
+    ↓
+resolveUrl(storageKey, presignedUrls)                     [line 761-771]
+    ├── If presignedUrls[storageKey] exists → use presigned URL
+    └── Fallback → resolveAssetPlaybackUrl (proxy URL)
+```
+
+### 2.5 Thread 4: Download Queue Processing
+
+```
+addToQueue(item: PreloadQueueItem)                        [line 494-530]
+    ├── Skip if already in queue or preloaded
+    ├── Insert in priority order (binary search insertion point)
+    └── Trigger processQueue()
+    ↓
+processQueue()                                            [line 355-491]
+    ├── Check: isOnline, queue not empty, not already processing
+    ├── maxConcurrent = recommendedConcurrency (network-aware)
+    ↓
+    While queue has items AND activeDownloads < maxConcurrent:
+        ├── Shift item from queue
+        ├── Skip if already preloaded (preloadedUrls.has(url))
+        ├── Skip if already cached (isUrlCached → StorageManager.hasAsset)
+        │   └── If cached: createReadyBlobUrl() for instant display
+        ↓
+        preloadWithProgress(url, jobId, assetId)          [line 140-234]
+            ├── Emit downloadEventBus.emitPreloadStart
+            ├── fetch(url) with streaming progress
+            ├── Collect chunks, emit progress events
+            ├── Store in Cache API: caches.open(assets).put(url, response)
+            └── Emit downloadEventBus.emitPreloadComplete
+        ↓
+        On success:
+            ├── createReadyBlobUrl(url, storageKey)
+            │   ├── StorageManager.getAsset(url) → blob
+            │   ├── URL.createObjectURL(blob) → blobUrl
+            │   ├── If image: decodeImage(blobUrl) → pre-paint ready
+            │   └── readyBlobUrlsRef.set(url, blobUrl)
+            └── Also cache under storageKey for post-refresh lookup
+        ↓
+        On failure (presigned URL CORS):
+            ├── markPresignedUrlFailed(storageKey)
+            ├── Build proxy URL: /api/file/download?privateUrl=...
+            └── Retry with proxy URL
+```
+
+### 2.6 Thread 5: Ready State & Instant Lookup
+
+```
+getReadyBlobUrl(url): string | null                       [line 582-584]
+    └── readyBlobUrlsRef.current.get(url) → O(1) Map lookup
+
+Usage in RuntimePresentation:
+    const resolveUrlWithBlob = (url) => {
+        const blobUrl = preloadOrchestrator.getReadyBlobUrl(url);
+        return blobUrl || resolveAssetPlaybackUrl(url);
+    };
+
+    <RuntimeElement resolveUrl={resolveUrlWithBlob} ... />
+```
+
+---
+
+## 3. ELEMENT TYPE → URL FIELD MAPPING (Complete Audit)
+
+### 3.1 All Element Types (11 total)
+
+| Element Type | URL Fields | Nested Arrays |
+|--------------|------------|---------------|
+| `navigation_next/prev` | iconUrl, transitionVideoUrl, reverseVideoUrl | - |
+| `gallery` | iconUrl, galleryHeaderImageUrl, galleryCarouselPrevIconUrl, galleryCarouselNextIconUrl, galleryCarouselBackIconUrl | galleryCards[].imageUrl, galleryInfoSpans[].iconUrl |
+| `carousel` | iconUrl, carouselPrevIconUrl, carouselNextIconUrl | carouselSlides[].imageUrl |
+| `video_player` | iconUrl, mediaUrl | - |
+| `audio_player` | iconUrl, mediaUrl | - |
+| `tooltip` | iconUrl | - |
+| `description` | iconUrl | - |
+| `spot` | iconUrl | - |
+| `logo` | iconUrl | - |
+| `popup` | iconUrl | - |
+
+### 3.2 Cross-Reference Verification
+
+**constructor.ts URL Fields vs preload.config.ts assetFields.all:**
+
+| Field in constructor.ts | In assetFields.all? | Status |
+|-------------------------|---------------------|--------|
+| iconUrl | Yes | OK |
+| mediaUrl | Yes | OK |
+| backgroundImageUrl | Yes | OK |
+| videoUrl | Yes | OK |
+| audioUrl | Yes | OK |
+| transitionVideoUrl | Yes | OK |
+| reverseVideoUrl | Yes | OK |
+| galleryHeaderImageUrl | Yes | OK |
+| carouselPrevIconUrl | Yes | OK |
+| carouselNextIconUrl | Yes | OK |
+| galleryCarouselPrevIconUrl | Yes | OK |
+| galleryCarouselNextIconUrl | Yes | OK |
+| galleryCarouselBackIconUrl | Yes | OK |
+
+**Nested Arrays vs nested config:**
+
+| Nested Array | In nested config? | Status |
+|--------------|-------------------|--------|
+| galleryCards | Yes | OK |
+| carouselSlides | Yes | OK |
+| galleryInfoSpans | Yes | OK |
+
+**Nested URL Fields vs nestedUrlFields:**
+
+| Field in Nested Items | In nestedUrlFields? | Status |
+|-----------------------|---------------------|--------|
+| galleryCards[].imageUrl | Yes | OK |
+| carouselSlides[].imageUrl | Yes | OK |
+| galleryInfoSpans[].iconUrl | Yes | OK |
+
+---
+
+## 4. OFFLINE MODE PROCESSING
+
+### 4.1 Storage Architecture
+
+```
+StorageManager                                [lib/offline/StorageManager.ts]
+    ├── Threshold: OFFLINE_CONFIG.storage.indexedDbMinSize (5MB)
+    ├── Small files (< 5MB): Cache API
+    │   └── caches.open('vm-assets').put(url, response)
+    └── Large files (≥ 5MB): IndexedDB via Dexie
+        └── OfflineDbManager.storeAsset(asset)
+
+hasAsset(url): Promise<boolean>
+    1. Check IndexedDB: OfflineDbManager.hasAssetByUrl(url)
+    2. Check Cache API: caches.open().match(url)
+
+getAsset(url): Promise<Blob | null>
+    1. Try IndexedDB: OfflineDbManager.getAssetByUrl(url)
+    2. Try Cache API: caches.open().match(url).blob()
+```
+
+### 4.2 Service Worker Integration
+
+```
+sw.ts (Serwist-generated)
+    ├── Precache: static assets (JS, CSS, fonts)
+    ├── Runtime caching strategies:
+    │   ├── API requests: NetworkFirst
+    │   └── Assets: CacheFirst
+    └── Offline fallback handling
+```
+
+---
+
+## 5. IMAGE PRE-DECODE FLOW
+
+### 5.1 extractPageImageUrls
+
+```
+extractPageImageUrls(page)                    [lib/imagePreDecode.ts:110-175]
+    ↓
+Extract background_image_url
+    ↓
+Parse ui_schema_json → elements[]
+    ↓
+For each element:
+    ├── Direct image fields (assetFields.images):
+    │   └── iconUrl, imageUrl, backgroundImageUrl, carousel*IconUrl, gallery*IconUrl, src
+    └── Nested arrays (assetFields.nested):
+        └── Filter nestedUrlFields to images only:
+            ├── imageUrl (in images array)
+            ├── iconUrl (in images array)
+            └── videoUrl (not in images - correctly excluded)
+```
+
+### 5.2 waitForPageImages
+
+```
+waitForPageImages(page, timeoutMs, cacheProvider)
+    ↓
+extractPageImageUrls(page) → imageUrls[]
+    ↓
+decodeImages(imageUrls, timeoutMs, cacheProvider)
+    ├── For each URL: decodeImage()
+    │   ├── If cacheProvider: try getCachedBlobUrl() → blob URL (local, fast)
+    │   └── new Image().decode() or onload fallback
+    └── Promise.race([all decoded, timeout])
+```
+
+---
+
+## 6. ROBUSTNESS VERIFICATION
+
+### 6.1 All Asset Types Covered
+
+| Asset Type | Extracted? | Preloaded? | Pre-decoded? | Cached? |
+|------------|------------|------------|--------------|---------|
+| Background images | Yes | Yes | Yes | Yes |
+| Background videos | Yes | Yes | N/A | Yes |
+| Background audio | Yes | Yes | N/A | Yes |
+| Element icons | Yes | Yes | Yes | Yes |
+| Transition videos | Yes | Yes | N/A | Yes |
+| Reverse videos | Yes | Yes | N/A | Yes |
+| Gallery cards images | Yes | Yes | Yes | Yes |
+| Gallery info span icons | Yes | Yes | Yes | Yes |
+| Gallery header image | Yes | Yes | Yes | Yes |
+| Gallery carousel icons | Yes | Yes | Yes | Yes |
+| Carousel slide images | Yes | Yes | Yes | Yes |
+| Carousel nav icons | Yes | Yes | Yes | Yes |
+| Media player URLs | Yes | Yes | N/A | Yes |
+
+### 6.2 Extraction Algorithm Robustness
+
+1. **extractPageLinks.ts** - Explicit field extraction
+   - Uses `assetFields.all` for top-level fields
+   - Uses `nested` + `nestedUrlFields` for nested arrays
+   - Handles all configured fields
+
+2. **useNeighborGraph.ts** - Recursive traversal
+   - `checkObject()` recursively traverses to depth 5
+   - Matches any field from `assetFields.all` at any nesting level
+   - Handles deeply nested structures
+
+3. **imagePreDecode.ts** - Image-only extraction
+   - Filters `nestedUrlFields` against `assetFields.images`
+   - Only pre-decodes actual images (not videos/audio)
+   - Correctly filters non-image URLs
+
+### 6.3 Edge Cases Handled
+
+| Edge Case | Handling |
+|-----------|----------|
+| Empty ui_schema_json | Returns empty arrays safely |
+| Missing nested arrays | Skipped gracefully |
+| Null/undefined values | Filtered out |
+| Already cached assets | Skipped download, creates blob URL |
+| Presigned URL CORS failure | Retries with proxy URL |
+| Network offline | Skips preloading, uses cache |
+| Large files (>=5MB) | Stored in IndexedDB instead of Cache API |
+
+---
+
+## 7. CONCLUSION
+
+The neighbor preloading system is **robust and comprehensive**:
+
+1. **Central Configuration** - All asset URL fields defined in `preload.config.ts`
+2. **Consistent Extraction** - All consumers use the same config
+3. **Complete Coverage** - All 11 element types and their URL fields are covered
+4. **Nested Arrays** - `galleryCards`, `carouselSlides`, `galleryInfoSpans` all handled
+5. **Dual Storage** - Cache API for small files, IndexedDB for large files
+6. **Fallback Handling** - Presigned URLs with proxy fallback
+7. **Network Awareness** - Adaptive concurrency based on connection
+
+**No gaps identified** - all asset types are properly extracted, preloaded, and cached.
+
+---
+
+## Related Documentation
+
+- [assets-preloading.md](../../documentation/assets-preloading.md) - E2E preloading feature documentation
+- [runtime-presentation.md](./runtime-presentation.md) - Runtime presentation viewer
+- [constructor-page-editor.md](./constructor-page-editor.md) - Constructor page editor
+- [hooks-module.md](./hooks-module.md) - Custom hooks reference
+- [lib-module.md](./lib-module.md) - Library utilities reference
diff --git a/frontend/docs/video-hooks-module.md b/frontend/docs/video-hooks-module.md
new file mode 100644
index 0000000..6d2d2f4
--- /dev/null
+++ b/frontend/docs/video-hooks-module.md
@@ -0,0 +1,495 @@
+# Video Hooks Module
+
+## Overview
+
+The Video Hooks module provides **8 primitive hooks** for video playback management. These hooks follow a composition pattern - smaller primitive hooks are combined to build complex video playback scenarios.
+
+**Location:** `frontend/src/hooks/video/`
+
+**Total Files:** 9 TypeScript files (8 hooks + 1 index file)
+
+**Architecture Pattern:** Primitive hooks that can be composed for different use cases:
+- **Transition video playback** - `useTransitionPlayback` uses `useVideoBlobUrl`, `useVideoTimeouts`
+- **UI element video player** - `useVideoPlayer` uses `useVideoPlaybackCore`
+- **Background video** - `useBackgroundVideoPlayback` uses primitives directly
+
+---
+
+## Hook Hierarchy
+
+```
+                    ┌─────────────────────────────┐
+                    │    Application Hooks         │
+                    │  (useTransitionPlayback,     │
+                    │   useBackgroundVideoPlayback)│
+                    └──────────────┬──────────────┘
+                                   │
+                    ┌──────────────▼──────────────┐
+                    │   Composite Hook             │
+                    │   useVideoPlaybackCore       │
+                    │   useVideoPlayer             │
+                    └──────────────┬──────────────┘
+                                   │
+        ┌──────────────────────────┼──────────────────────────┐
+        │                          │                          │
+┌───────▼───────┐    ┌─────────────▼─────────────┐  ┌─────────▼─────────┐
+│ useVideoBlobUrl│    │ useVideoBufferingState    │  │ useVideoFirstFrame│
+│ URL resolution │    │ Buffering detection       │  │ First frame detect│
+└───────────────┘    └───────────────────────────┘  └───────────────────┘
+        │                          │                          │
+┌───────▼───────┐    ┌─────────────▼─────────────┐  ┌─────────▼─────────┐
+│useVideoEvent  │    │ useVideoErrorRecovery     │  │ useVideoTimeouts  │
+│Manager        │    │ Error handling + retry    │  │ Timeout management│
+└───────────────┘    └───────────────────────────┘  └───────────────────┘
+```
+
+---
+
+## Primitive Hooks
+
+### useVideoEventManager
+
+**File:** `useVideoEventManager.ts` (~90 LOC)
+
+**Purpose:** Centralizes video element event listener management with automatic cleanup.
+
+```typescript
+type VideoEventType = 'play' | 'pause' | 'ended' | 'timeupdate' | 'waiting' |
+                      'canplay' | 'playing' | 'loadedmetadata' | 'error' | 'progress';
+
+interface UseVideoEventManagerOptions {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  handlers: Partial<Record<VideoEventType, () => void>>;
+  enabled?: boolean;
+}
+
+const useVideoEventManager = (options: UseVideoEventManagerOptions): void;
+```
+
+**Usage:**
+```typescript
+useVideoEventManager({
+  videoRef,
+  handlers: {
+    playing: () => setIsPlaying(true),
+    ended: () => setIsPlaying(false),
+    waiting: () => setIsBuffering(true),
+    canplay: () => setIsBuffering(false),
+  },
+  enabled: !!videoUrl,
+});
+```
+
+---
+
+### useVideoBufferingState
+
+**File:** `useVideoBufferingState.ts` (~180 LOC)
+
+**Purpose:** Tracks video buffering state with debouncing to avoid UI flicker.
+
+```typescript
+interface UseVideoBufferingStateOptions {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  onBufferingChange?: (isBuffering: boolean) => void;
+  debounceMs?: number;  // Default: 100ms
+}
+
+interface UseVideoBufferingStateResult {
+  isBuffering: boolean;
+  isWaitingForData: boolean;
+  bufferedRanges: TimeRanges | null;
+  bufferedPercent: number;
+}
+```
+
+**Key Features:**
+- Debounced state changes to prevent rapid UI updates
+- Tracks `waiting` and `canplay` events
+- Computes buffered percentage for progress display
+- Handles edge cases like `readyState` checks
+
+---
+
+### useVideoBlobUrl
+
+**File:** `useVideoBlobUrl.ts` (~150 LOC)
+
+**Purpose:** Resolves video URLs to blob URLs from preload cache for instant playback.
+
+```typescript
+interface PreloadCacheProvider {
+  getReadyBlobUrl?: (url: string) => string | null;
+  getReadyBlob?: (url: string) => Blob | null;
+  getCachedBlobUrl?: (url: string) => Promise<string | null>;
+}
+
+interface UseVideoBlobUrlOptions {
+  videoUrl: string | undefined;
+  storageKey?: string;
+  preloadCache?: PreloadCacheProvider;
+  enabled?: boolean;
+}
+
+interface UseVideoBlobUrlResult {
+  resolvedUrl: string | null;
+  isFromCache: boolean;
+  isResolving: boolean;
+}
+```
+
+**Resolution Priority:**
+1. `getReadyBlob(storageKey)` → Create fresh blob URL (avoids decoder issues)
+2. `getReadyBlobUrl(storageKey)` → In-memory blob URL (O(1) lookup)
+3. `getReadyBlobUrl(videoUrl)` → Fallback lookup by resolved URL
+4. `getCachedBlobUrl()` → Cache API/IndexedDB lookup
+5. Return original `videoUrl` → Network fetch
+
+**Usage:**
+```typescript
+const { resolvedUrl, isFromCache } = useVideoBlobUrl({
+  videoUrl: transition.videoUrl,
+  storageKey: transition.storageKey,
+  preloadCache: preloadOrchestrator,
+  enabled: !!transition,
+});
+```
+
+---
+
+### useVideoFirstFrame
+
+**File:** `useVideoFirstFrame.ts` (~130 LOC)
+
+**Purpose:** Detects when the first video frame has been rendered using `requestVideoFrameCallback`.
+
+```typescript
+interface UseVideoFirstFrameOptions {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  onFirstFrame?: () => void;
+  enabled?: boolean;
+}
+
+interface UseVideoFirstFrameResult {
+  isFirstFrameRendered: boolean;
+  reset: () => void;
+}
+```
+
+**Key Features:**
+- Uses `requestVideoFrameCallback` API (Safari 15.4+, Chrome 83+)
+- Falls back to `playing` event for older browsers
+- Provides `reset()` for reuse across video changes
+
+---
+
+### useVideoErrorRecovery
+
+**File:** `useVideoErrorRecovery.ts` (~160 LOC)
+
+**Purpose:** Handles video errors with automatic retry and presigned URL fallback.
+
+```typescript
+interface UseVideoErrorRecoveryOptions {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  currentUrl: string | null;
+  storageKey?: string;
+  maxRetries?: number;  // Default: 2
+  onRecoveryAttempt?: (newUrl: string) => void;
+  onRecoveryFailed?: (error: string) => void;
+}
+
+interface UseVideoErrorRecoveryResult {
+  errorCount: number;
+  lastError: string | null;
+  isRecovering: boolean;
+  currentResolvedUrl: string | null;
+}
+```
+
+**Recovery Strategy:**
+1. First error → Mark presigned URL failed, retry with proxy URL
+2. Second error → Retry with fresh presigned URL request
+3. Third error → Call `onRecoveryFailed`
+
+---
+
+### useVideoTimeouts
+
+**File:** `useVideoTimeouts.ts` (~80 LOC)
+
+**Purpose:** Manages timeout IDs for video playback operations with automatic cleanup.
+
+```typescript
+interface UseVideoTimeoutsResult {
+  setLoadTimeout: (callback: () => void, ms: number) => void;
+  setPlayTimeout: (callback: () => void, ms: number) => void;
+  setFinishTimeout: (callback: () => void, ms: number) => void;
+  clearAllTimeouts: () => void;
+}
+```
+
+**Usage:**
+```typescript
+const timeouts = useVideoTimeouts();
+
+// Set load timeout
+timeouts.setLoadTimeout(() => {
+  console.warn('Video load timed out');
+  onError?.('load-timeout');
+}, 10000);
+
+// Clear on success
+video.oncanplay = () => timeouts.clearAllTimeouts();
+```
+
+---
+
+## Composite Hooks
+
+### useVideoPlaybackCore
+
+**File:** `useVideoPlaybackCore.ts` (~280 LOC)
+
+**Purpose:** Core video playback logic combining multiple primitives. Used by `useVideoPlayer`.
+
+```typescript
+interface UseVideoPlaybackCoreOptions {
+  videoRef: RefObject<HTMLVideoElement | null>;
+  videoUrl: string | undefined;
+  storageKey?: string;
+  autoplay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  startTime?: number | null;
+  endTime?: number | null;
+  preloadCache?: PreloadCacheProvider;
+  onReady?: () => void;
+  onEnded?: () => void;
+  onError?: (error: string) => void;
+}
+
+interface UseVideoPlaybackCoreResult {
+  // State
+  isReady: boolean;
+  isPlaying: boolean;
+  isBuffering: boolean;
+  isEnded: boolean;
+  currentTime: number;
+  duration: number;
+
+  // Resolved URL
+  resolvedUrl: string | null;
+  isFromCache: boolean;
+
+  // Controls
+  play: () => Promise<void>;
+  pause: () => void;
+  seek: (time: number) => void;
+  reset: () => void;
+}
+```
+
+**Composes:**
+- `useVideoBlobUrl` - URL resolution
+- `useVideoBufferingState` - Buffering tracking
+- `useVideoFirstFrame` - Ready detection
+- `useVideoErrorRecovery` - Error handling
+- `useVideoEventManager` - Event listeners
+
+---
+
+### useVideoPlayer
+
+**File:** `useVideoPlayer.ts` (~200 LOC)
+
+**Purpose:** Complete video player hook for UI elements (VideoPlayerElement). Wraps `useVideoPlaybackCore` with UI-specific features.
+
+```typescript
+interface UseVideoPlayerOptions extends UseVideoPlaybackCoreOptions {
+  // Inherited from UseVideoPlaybackCoreOptions
+  showControls?: boolean;
+  posterUrl?: string;
+  onFirstPlay?: () => void;
+}
+
+interface UseVideoPlayerResult extends UseVideoPlaybackCoreResult {
+  // Additional UI state
+  hasPlayedOnce: boolean;
+  showPoster: boolean;
+  progress: number;  // 0-100
+
+  // UI Controls
+  togglePlay: () => void;
+  toggleMute: () => void;
+  setVolume: (volume: number) => void;
+}
+```
+
+**Usage in VideoPlayerElement:**
+```typescript
+const player = useVideoPlayer({
+  videoRef,
+  videoUrl: element.videoUrl,
+  storageKey: element.videoStoragePath,
+  autoplay: element.autoplay ?? false,
+  loop: element.loop ?? false,
+  muted: element.muted ?? true,
+  preloadCache: preloadOrchestrator,
+  onReady: () => console.log('Video ready'),
+});
+
+return (
+  <div>
+    <video ref={videoRef} src={player.resolvedUrl} />
+    {player.showPoster && <img src={posterUrl} />}
+    <button onClick={player.togglePlay}>
+      {player.isPlaying ? 'Pause' : 'Play'}
+    </button>
+    <progress value={player.progress} max={100} />
+  </div>
+);
+```
+
+---
+
+## Index Exports
+
+**File:** `index.ts` (~60 LOC)
+
+```typescript
+// Primitive hooks
+export { useVideoEventManager } from './useVideoEventManager';
+export { useVideoBufferingState } from './useVideoBufferingState';
+export { useVideoBlobUrl } from './useVideoBlobUrl';
+export { useVideoFirstFrame } from './useVideoFirstFrame';
+export { useVideoErrorRecovery } from './useVideoErrorRecovery';
+export { useVideoTimeouts } from './useVideoTimeouts';
+
+// Composite hooks
+export { useVideoPlaybackCore } from './useVideoPlaybackCore';
+export { useVideoPlayer } from './useVideoPlayer';
+
+// Types
+export type { PreloadCacheProvider } from './useVideoBlobUrl';
+```
+
+---
+
+## Integration with useTransitionPlayback
+
+The `useTransitionPlayback` hook uses video primitives for transition video playback:
+
+```typescript
+// useTransitionPlayback.ts
+import { useVideoBlobUrl, useVideoTimeouts, type PreloadCacheProvider } from './video';
+
+export function useTransitionPlayback(options) {
+  const { transition, videoRef, preloadCache } = options;
+
+  // Resolve blob URL from cache
+  const { resolvedUrl, isFromCache } = useVideoBlobUrl({
+    videoUrl: transition?.videoUrl,
+    storageKey: transition?.storageKey,
+    preloadCache,
+    enabled: !!transition,
+  });
+
+  // For back navigation, also resolve reverse video
+  const { resolvedUrl: reverseUrl } = useVideoBlobUrl({
+    videoUrl: transition?.reverseVideoUrl,
+    storageKey: transition?.reverseStorageKey,
+    preloadCache,
+    enabled: transition?.isBack && !!transition?.reverseVideoUrl,
+  });
+
+  // Manage timeouts
+  const timeouts = useVideoTimeouts();
+
+  // ... playback logic
+}
+```
+
+---
+
+## Design Patterns
+
+### 1. Primitive Composition
+
+Each primitive hook handles one concern:
+- Event management → `useVideoEventManager`
+- Buffering state → `useVideoBufferingState`
+- URL resolution → `useVideoBlobUrl`
+
+Composite hooks combine primitives:
+```typescript
+function useVideoPlaybackCore(options) {
+  const { resolvedUrl } = useVideoBlobUrl(options);
+  const { isBuffering } = useVideoBufferingState({ videoRef });
+  const { isFirstFrameRendered } = useVideoFirstFrame({ videoRef });
+  // ... combine state
+}
+```
+
+### 2. Enabled Pattern
+
+All hooks accept an `enabled` prop to conditionally activate:
+```typescript
+const { resolvedUrl } = useVideoBlobUrl({
+  videoUrl,
+  enabled: !!videoUrl && isActive,  // Only resolve when needed
+});
+```
+
+### 3. Callback Refs
+
+Expensive operations use refs to avoid re-renders:
+```typescript
+const timeoutIdsRef = useRef<Map<string, NodeJS.Timeout>>(new Map());
+
+const setLoadTimeout = useCallback((cb, ms) => {
+  const id = setTimeout(cb, ms);
+  timeoutIdsRef.current.set('load', id);
+}, []);
+```
+
+### 4. Cleanup on Unmount
+
+All hooks properly cleanup:
+```typescript
+useEffect(() => {
+  // Setup event listeners
+  return () => {
+    // Cleanup
+    timeoutIdsRef.current.forEach(clearTimeout);
+    timeoutIdsRef.current.clear();
+  };
+}, []);
+```
+
+---
+
+## Related Documentation
+
+- [Hooks Module](./hooks-module.md) - Parent hooks documentation
+- [Navigation & Smooth Transitions](./navigation-smooth-transitions.md) - Transition playback integration
+- [Assets Preloading](../../documentation/assets-preloading.md) - Blob URL caching
+- [Video Playback](../../documentation/video-playback.md) - Background video implementation
+
+---
+
+## Summary
+
+| Hook | Type | LOC | Purpose |
+|------|------|-----|---------|
+| `useVideoEventManager` | Primitive | ~90 | Event listener management |
+| `useVideoBufferingState` | Primitive | ~180 | Buffering state tracking |
+| `useVideoBlobUrl` | Primitive | ~150 | URL resolution from cache |
+| `useVideoFirstFrame` | Primitive | ~130 | First frame detection |
+| `useVideoErrorRecovery` | Primitive | ~160 | Error handling + retry |
+| `useVideoTimeouts` | Primitive | ~80 | Timeout management |
+| `useVideoPlaybackCore` | Composite | ~280 | Core playback logic |
+| `useVideoPlayer` | Composite | ~200 | UI video player |
+| **Total** | | **~1,270** | |
+
+The video hooks module provides reusable primitives that can be composed for any video playback scenario - from transition videos to background videos to UI element players.