Document storage mode fixes

Author: OpenHypervideo

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 FrameTrail is an open hypervideo environment for creating, annotating, and remixing interactive videos. It's a client-side JavaScript application with an optional PHP backend that uses **JSON files instead of a database** for all data storage. The entire system is portable — copy the `_data` directory between servers and everything works.
 
-FrameTrail can run in three modes: with a PHP server (full multi-user), with the File System Access API for local editing (no server needed), or as a read-only viewer.
+FrameTrail can run in three modes: with a PHP server (full multi-user), with the File System Access API for local editing in Chrome/Edge (no server needed), or in-memory using the Download adapter (view + edit + export, no persistence — works everywhere but requires data to be passed via init options).
 
 ## Repository Structure
 
@@ -136,7 +136,7 @@ Note: Some libraries have custom/patched versions (raphael-connections.js, rapha
 - `'server'` — PHP backend available, data loaded/saved via AJAX to `src/_server/ajaxServer.php`
 - `'local'` — File System Access API active, data read/written via `StorageAdapterLocal` to a user-selected folder
 - `'needsFolder'` — File System Access API supported but no folder selected yet; launcher prompts user to pick a `_data` directory
-- `'noStorage'` — No storage backend available (Firefox/Safari on `file://`); app cannot load or save data
+- `'download'` — No persistent storage available (Firefox/Safari, or any browser without File System Access API and no PHP); `StorageAdapterDownload` is used, which stores data in memory and lets users export/download it. Viewing and editing work; saves persist only until page reload.
 
 ### Application Modes
 

README.md

@@ -12,11 +12,10 @@ FrameTrail is an open-source platform for building non-linear, interactive video
 
 ## Features
 
-### Three Ways to Run
+### Two Ways to Run
 
 1. **Server mode** (Apache + PHP) — Full multi-user editing, file uploads, user management
 2. **Local folder mode** (Chrome/Edge) — Full editing without a server, using the File System Access API to read/write a local `_data` folder
-3. **Read-only mode** — Open `index.html` directly in any browser to view existing hypervideos
 
 ### Editing
 
@@ -52,8 +51,8 @@ FrameTrail supports a wide range of embeddable content:
 ### Browser Support
 
 - **Desktop:** Chrome, Firefox, Edge (latest versions)
-- **Local folder mode:** Chrome/Edge (requires File System Access API)
-- **Mobile:** Player works, editing disabled
+- **Local folder mode:** Chrome/Edge only (requires File System Access API)
+- **Mobile:** Player works in server mode; editing is disabled
 
 ---
 
@@ -75,11 +74,6 @@ FrameTrail supports a wide range of embeddable content:
 3. When prompted, select or create a `_data` folder on your computer
 4. Full editing — all changes saved directly to your local files
 
-### Option 3: Read-Only Viewing
-
-1. Open `index.html` in any modern browser
-2. If a `_data` folder with hypervideo data exists alongside the HTML files, it will be loaded for viewing
-
 ---
 
 ## Getting Started

docs/ARCHITECTURE.md

@@ -259,7 +259,7 @@ FrameTrail.changeState('editMode', true);
 | `target` | String | CSS selector for mount point |
 | `editMode` | Boolean/String | `false`, `'overlays'`, `'annotations'`, etc. |
 | `viewMode` | String | `'video'`, `'overview'`, `'resources'` |
-| `storageMode` | String | `'server'`, `'local'`, `'needsFolder'`, `'noStorage'` |
+| `storageMode` | String | `'server'`, `'local'`, `'needsFolder'`, `'download'` |
 | `loggedIn` | Boolean | User authentication status |
 | `username` | String | Current user's name |
 | `fullscreen` | Boolean | Fullscreen state |
@@ -293,21 +293,24 @@ FrameTrail uses a strategy pattern for data persistence. The `StorageManager` mo
 
 | Adapter | Class | When Used |
 |---------|-------|-----------|
-| Server | `StorageAdapterServer` | Running on Apache+PHP (`document.location.host` exists) |
-| Local | `StorageAdapterLocal` | File System Access API available (Chrome/Edge, file://) |
-| Download | `StorageAdapterDownload` | Fallback — enables Save As/export |
+| Server | `StorageAdapterServer` | HTTP/HTTPS with PHP backend responding at `_server/ajaxServer.php` |
+| Local | `StorageAdapterLocal` | File System Access API available (Chrome/Edge) and folder selected |
+| Download | `StorageAdapterDownload` | Supplemental — provides Save As/export in either mode |
 
 All adapters implement the same interface, so the rest of the application doesn't need to know which storage backend is active.
 
 ### Storage Mode Detection
 
-The `PlayerLauncher` (or `ResourceManagerLauncher`) detects the environment:
+`StorageManager.init()` determines the storage mode at startup:
 
-1. If `document.location.host` is set → `'server'` mode (PHP backend available)
-2. If File System Access API is supported → `'needsFolder'` (prompt user to select `_data` folder)
-3. Otherwise → `'noStorage'` (read-only fallback)
+1. If on HTTP/HTTPS **and** PHP backend responds at `_server/ajaxServer.php` → `'server'`
+2. If on HTTP/HTTPS **but** PHP is unreachable, or on `file://` protocol:
+   - If File System Access API is supported (Chrome/Edge) → try to restore a previously saved folder handle
+     - Handle restored → `'local'`
+     - No handle saved → `'needsFolder'` (folder picker dialog is shown)
+   - File System Access API not supported (Firefox/Safari) → `'download'`
 
-Once a folder is selected in `'needsFolder'` mode, the state transitions to `'local'`.
+In `'download'` mode the `StorageAdapterDownload` is used: data is stored in memory, and users can export their work as JSON via the Save As dialog. Viewing and editing both work. Once a folder is selected in `'needsFolder'` mode, the state transitions to `'local'`.
 
 ## Data Model
 

docs/DEPLOYMENT.md

@@ -58,21 +58,11 @@ The `StorageAdapterLocal` class uses the File System Access API (`showDirectoryP
 - No PHP-based file processing (image optimization, video transcoding)
 - Browser must support File System Access API (Chrome/Edge only)
 
-### Option 3: Read-Only Viewing
+### Save As / Export
 
-View existing hypervideos without any editing capability.
+The `StorageAdapterDownload` is used as the fallback storage backend when no PHP server and no local folder are available (`storageMode: 'download'`). It stores all data in memory and exposes a Save As dialog that downloads a JSON snapshot of the current state.
 
-**Steps:**
-
-1. Open `index.html` in any modern browser
-2. If a `_data` folder with hypervideo data exists alongside the HTML files, FrameTrail loads it for viewing
-3. No editing, no saving — purely a viewer
-
-**Note:** Firefox supports loading local files via AJAX when opening `index.html` from the filesystem. Chrome blocks this by default.
-
-### Option 4: Save As / Download Mode
-
-When neither a server nor the File System Access API is available, FrameTrail falls back to the `StorageAdapterDownload`. Users can still create and edit hypervideos, then export the data as downloadable files via the browser's download mechanism. This is useful for one-off editing or as a fallback on unsupported browsers.
+In server and local modes, Save As is also available as a supplemental export tool — useful for archiving or migrating content between instances.
 
 ## Embedding FrameTrail
 
@@ -105,12 +95,15 @@ $(document).ready(function() {
 </script>
 ```
 
-### With Inline Data (No Server)
+### With Inline Data
+
+When running in server mode, you can pass all hypervideo and resource data directly via init options, bypassing the `_data/` directory entirely. This is useful for embedding a specific hypervideo on a page without managing the data folder.
 
 ```javascript
 FrameTrail.init({
     target: '#container',
     startID: '0',
+    config: { theme: 'dark' },
     contents: [{
         hypervideo: {
             meta: { name: 'My Video', creator: 'Anonymous', creatorId: 'anon',
@@ -121,14 +114,21 @@ FrameTrail.init({
             subtitles: {},
             globalEvents: {},
             customCSS: ''
-        }
+        },
+        annotations: []
     }],
-    resources: {
-        'my-video': { name: 'Main Video', type: 'youtube', src: 'dQw4w9WgXcQ' }
-    }
+    resources: [{
+        label: 'Inline resources',
+        type: 'frametrail',
+        data: {
+            'my-video': { name: 'Main Video', type: 'youtube', src: 'dQw4w9WgXcQ' }
+        }
+    }]
 }, 'PlayerLauncher');
 ```
 
+**Note:** When no PHP server and no local folder are available, FrameTrail falls back to `storageMode: 'download'` — the `StorageAdapterDownload` holds data in memory. Inline data init options work fully in this mode: viewing and editing are both functional, and changes can be exported via the Save As dialog. Nothing persists past a page reload unless exported.
+
 See [docs/ARCHITECTURE.md](ARCHITECTURE.md) for the full initialization options reference.
 
 ## Building from Source